Magicweave: Spin the Wheel

This guide is for frontend and game developers integrating the Spin the Wheel feature using the Magicweave.

The client_spin_wheel module lets your game:

• retrieve active spin wheels for your project
• read the current state and allowance (free, bonus, and paid spins) for a user
• run immediate spins that credit rewards automatically
• run dry spins with a delayed claim using a claim_token

Base URL and route prefix

Production-style base URL (same host pattern as other client modules):

• https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/

Spin wheel routes are under:

• /wheels

With a combined client mount, prefix with /client (for example /client/wheels).

Required authentication and headers

All spin wheel endpoints require:

• x-client-id: <your_project_client_id>
• x-client-secret: <your_project_client_secret>
• Authorization: Bearer <magicweave_access_token>
• Content-Type: application/json

The authenticated user must have the client.spin_wheel permission.

Target a wheel: ID vs. key slug

Most endpoints exist in two variants:

• By numeric ID: /wheels/{wheel_config_id}/...
• By key slug: /wheels/by-key/{key_slug}/...

Using key_slug is usually easier for clients: it stays stable across environments, while the integer wheel_config_id may differ per environment or migration.

Endpoint 1: List active wheels

GET /wheels

Returns every active wheel for the project plus the global cooldown between spins.

Example response:

{
  "wheels": [
    {
      "id": 1,
      "name": "Daily Spin"
    }
  ],
  "cooldown_seconds": 2
}

Reference: List active spin wheels

Endpoint 2: Get wheel state

GET /wheels/{wheel_config_id}/state
GET /wheels/by-key/{key_slug}/state

Returns allowances and timing for that wheel for the current user.

Example response:

{
  "wheel_config_id": 1,
  "cooldown_seconds": 2,
  "period_ends_at": "2023-12-01T23:59:59Z",
  "daily_free_spins": 1,
  "free_spins_used": 0,
  "free_spins_remaining": 1,
  "bonus_spins_remaining": 0,
  "paid_spin_available": true,
  "paid_spin_currency_key": "gems",
  "paid_spin_currency_amount": 50
}

References:

• Get wheel state by key slug
• Get wheel state by wheel config id

Endpoint 3: Get wheel detail

GET /wheels/{wheel_config_id}
GET /wheels/by-key/{key_slug}

Same fields as state, plus segments: the slices currently on the wheel (sort order, labels, reward configuration) so you can render the wheel UI.

Example segments entry:

{
  "sort_order": 0,
  "segment_id": 101,
  "label": "100 Coins",
  "reward": {
    "type": "currency",
    "amount": 100
  }
}

References:

• Get wheel detail by key slug
• Get wheel detail by wheel config id

Endpoint 4: Immediate spin

POST /wheels/{wheel_config_id}/spin
POST /wheels/by-key/{key_slug}/spin

Runs a spin and credits the reward immediately. The backend picks free → bonus → paid automatically.

Example response:

{
  "segment_id": 101,
  "label": "100 Coins",
  "reward": {
    "reward_type": "currency",
    "payload": {
      "amount": 100,
      "currency": "coins"
    }
  },
  "spin_kind": "free"
}

References:

• Immediate spin by key slug
• Immediate spin by wheel config id

Endpoint 5: Dry spin (delayed claim)

POST /wheels/{wheel_config_id}/dry-spin
POST /wheels/by-key/{key_slug}/dry-spin

Consumes the appropriate spin allowance (same priority as immediate spin) but does not credit the reward yet. Returns a claim_token to redeem after your animation.

Example response:

{
  "claim_token": "abc123xyz...",
  "segment_id": 101,
  "label": "100 Coins",
  "reward": {
    "reward_type": "currency",
    "payload": {
      "amount": 100,
      "currency": "coins"
    }
  },
  "spin_kind": "paid"
}

References:

• Dry spin by key slug
• Dry spin by wheel config id

Endpoint 6: Claim spin reward

POST /wheels/{wheel_config_id}/claim-spin-reward
POST /wheels/by-key/{key_slug}/claim-spin-reward

Request body:

{
  "claim_token": "abc123xyz..."
}

Response matches the immediate spin shape (segment, label, reward, spin_kind).

References:

• Claim dry spin reward by key slug
• Claim dry spin reward by wheel config id

Error codes and rejection reasons

HTTP	Situation
404	Wheel not found / wheel_not_found_or_inactive: unknown or inactive wheel id or slug. pending_spin_not_found: invalid or expired claim_token.
402	no_spins_available: no free or bonus spins and paid spins unavailable. insufficient_currency_for_spin: paid spin required but balance too low.
409	pending_spin_already_claimed: claim_token already redeemed.
400	wheel_has_no_segments: wheel has no valid segments.
500	wheel_probability_misconfigured: segment probabilities do not sum correctly on the server.

Also expect 401 / 403 for missing credentials or missing client.spin_wheel permission.

Client integration notes

• Spin priority: the backend uses free → bonus → paid. Use paid_spin_currency_amount (and paid_spin_currency_key) from state to show paid spin cost when free and bonus are exhausted.
• Visuals: call the wheel detail endpoint to preload segments so the client draws the correct labels and weights.
• Animations: use dry spin when the outcome must be fixed before the animation ends, then claim when the animation completes so rewards stay server-authoritative.

cURL examples (by key slug)

Replace host, credentials, and daily-spin as needed.

List wheels

curl -sS -X GET "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/wheels" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"

State

curl -sS -X GET "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/wheels/by-key/daily-spin/state" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"

Immediate spin

curl -sS -X POST "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/wheels/by-key/daily-spin/spin" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"

Dry spin then claim

curl -sS -X POST "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/wheels/by-key/daily-spin/dry-spin" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"

curl -sS -X POST "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/wheels/by-key/daily-spin/claim-spin-reward" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"claim_token":"<token-from-dry-spin>"}'

For the numeric wheel config id variants, swap the path prefix from /wheels/by-key/{key_slug} to /wheels/{wheel_config_id} on the same suffixes (/state, ``, /spin, /dry-spin, /claim-spin-reward).