API Reference

The Oncade Server API lets you manage account linking, products, wallets and purchases from your game servers. All requests require HTTPS and include authentication headers.

NOTE: we also provide the Oncade API Test Dashboard. You can try out requests live at Oncade API Test Dashboard.

Common headers

Every request must include the Authorization header with Bearer <your_api_key> and X-Oncade-API-Version (defaults to v1). Game endpoints require X-Game-Id with a server API key. Campaign endpoints (/v1/campaign/...) require X-Campaign-Id with a campaign API key. For POST and PUT requests, supply an Idempotency-Key to safely retry requests without creating duplicates.

Get GameGET

/v1/game

Fetch game details for the game associated with the API key.

curl -X GET https://oncade.gg/api/v1/game \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "gameId": "test-game",
  "name": "Test Game",
  "description": "An awesome test game",
  "imageUrl": "https://example.com/image.png",
  "smallImageUrl": "https://example.com/small.png",
  "storeImageUrl": "https://example.com/store.png",
  "demoUrl": "https://example.com/demo",
  "demoImageUrl": "https://example.com/demo-image.png",
  "steamAppId": "12345",
  "discordUrl": "https://discord.gg/test",
  "screenshots": [
    "https://example.com/ss1.png",
    "https://example.com/ss2.png"
  ],
  "movies": [
    "https://example.com/trailer.mp4"
  ],
  "hideSuccessPageShareButtons": false,
  "status": "approved",
  "environment": "test",
  "affiliateRate": 10,
  "enableTip": true,
  "isVisible": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-02T00:00:00.000Z"
}
Go to top

Create Virtual CurrencyPOST

/v1/vc/currencies

Define a virtual currency for your game. Requires an Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/vc/currencies \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 021e7318-2654-4b68-be5b-b3e325e1da2d" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "GEM",
  "name": "Gems"
}'

Example Response

{
  "currency": {
    "_id": "cur_123",
    "code": "GEM",
    "name": "Gems",
    "status": "active"
  }
}
Go to top

List Virtual CurrenciesGET

/v1/vc/currencies

Return paginated virtual currencies for the authenticated game.

curl -X GET https://oncade.gg/api/v1/vc/currencies?page=1&limit=20 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "items": [
    {
      "_id": "cur_123",
      "code": "GEM",
      "name": "Gems",
      "status": "active"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Update Virtual CurrencyPATCH

/v1/vc/currencies/{currencyId}

Update currency fields. All body params are optional.

curl -X PATCH https://oncade.gg/api/v1/vc/currencies/cur_123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -d '{
  "name": "Gems+",
  "status": "paused"
}'
Go to top

Get User BalanceGET

/v1/vc/balances

Fetch a player balance for the specified currency.

curl -X GET https://oncade.gg/api/v1/vc/balances?currencyId=cur_123&userRef=link_usr_abc \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "currencyId": "cur_123",
  "userRef": "link_usr_abc",
  "balanceUnits": "500",
  "updatedAt": "2024-05-01T00:00:00.000Z"
}
Go to top

List Journal EntriesGET

/v1/vc/journals

Return paginated ledger entries for a player and currency. Results are sorted newest-first.

curl -X GET https://oncade.gg/api/v1/vc/journals?currencyId=cur_123&userRef=link_usr_abc \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "items": [
    {
      "_id": "jrnl_001",
      "type": "credit",
      "postings": [
        {
          "account": {
            "type": "pool",
            "address": "wallet-placeholder"
          },
          "deltaUnits": "-500"
        },
        {
          "account": {
            "type": "user",
            "userRef": "link_usr_abc"
          },
          "deltaUnits": "500"
        }
      ],
      "createdAt": "2024-05-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Credit Player BalancePOST

/v1/vc/credits

Move units from the treasury into a player balance. Requires an Idempotency-Key header. Returns 201 with a journal entry.

curl -X POST https://oncade.gg/api/v1/vc/credits \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: f5465b4f-c8af-4a10-aadc-e0ce7f0ce009" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "userRef": "link_usr_abc",
  "amountUnits": "500",
  "orderId": "order-123"
}'

Example Response

{
  "journalId": "jrnl_002",
  "newBalanceUnits": "1500",
  "breakdown": [
    {
      "participant": "pool",
      "direction": "debit",
      "amountUnits": "500",
      "description": "Credit to user"
    },
    {
      "participant": "user",
      "direction": "credit",
      "userRef": "link_usr_abc",
      "amountUnits": "500",
      "description": "Credit to user"
    }
  ]
}
Go to top

Debit Player BalancePOST

/v1/vc/debits

Remove units from a player balance and return them to the treasury. Requires an Idempotency-Key header. Returns 201 with a journal entry.

curl -X POST https://oncade.gg/api/v1/vc/debits \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 9290b26c-d51d-4815-aba7-1559c4e6fdee" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "userRef": "link_usr_abc",
  "amountUnits": "250",
  "reason": "refund"
}'

Example Response

{
  "journalId": "jrnl_003",
  "newBalanceUnits": "1250",
  "breakdown": [
    {
      "participant": "user",
      "direction": "debit",
      "userRef": "link_usr_abc",
      "amountUnits": "250",
      "description": "Refund"
    },
    {
      "participant": "pool",
      "direction": "credit",
      "amountUnits": "250",
      "description": "Refund"
    }
  ]
}
Go to top

Batch Debit with DistributionPOST

/v1/vc/batch

Atomically debit one player and distribute to multiple recipients. All-or-nothing — the total is the sum of recipient amounts. Requires an Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/vc/batch \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: e940462f-546c-46b4-8e10-566e439746c0" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "sourceUserRef": "link_usr_player1",
  "recipients": "[\n  {\n    \"userRef\": \"link_usr_winner1\",\n    \"amountUnits\": \"100\",\n    \"description\": \"First place\"\n  },\n  {\n    \"userRef\": \"link_usr_winner2\",\n    \"amountUnits\": \"50\",\n    \"description\": \"Second place\"\n  },\n  {\n    \"toPool\": true,\n    \"amountUnits\": \"25\",\n    \"description\": \"Pool contribution\"\n  },\n  {\n    \"toPool\": true,\n    \"amountUnits\": \"25\",\n    \"description\": \"Game wallet fee\"\n  }\n]"
}'

Example Response

{
  "journalId": "jrnl_batch_001",
  "newBalanceUnits": "800",
  "breakdown": [
    {
      "participant": "user",
      "direction": "debit",
      "userRef": "link_usr_player1",
      "amountUnits": "200",
      "description": "Batch transaction debit"
    },
    {
      "participant": "user",
      "direction": "credit",
      "userRef": "link_usr_winner1",
      "amountUnits": "100",
      "description": "First place"
    },
    {
      "participant": "user",
      "direction": "credit",
      "userRef": "link_usr_winner2",
      "amountUnits": "50",
      "description": "Second place"
    },
    {
      "participant": "pool",
      "direction": "credit",
      "amountUnits": "25",
      "description": "Pool contribution"
    },
    {
      "participant": "pool",
      "direction": "credit",
      "amountUnits": "25",
      "description": "Game wallet fee"
    }
  ]
}
Go to top

Create Cashout RequestPOST

/v1/vc/cashouts

Stage a cashout for manual review. Balance is not debited until approval. Requires an Idempotency-Key header. Returns 201.

curl -X POST https://oncade.gg/api/v1/vc/cashouts \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 642d71a7-c5f7-4365-b6d8-d1b93d4c1a9f" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "userRef": "link_usr_abc",
  "units": "2000"
}'

Example Response

{
  "cashoutRequestId": "co_001"
}
Go to top

List Cashout RequestsGET

/v1/vc/cashouts

Return cashout requests for a player with pagination, optionally filtered by status.

curl -X GET https://oncade.gg/api/v1/vc/cashouts?currencyId=cur_123&status=pendingReview&page=1&limit=20 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "items": [
    {
      "_id": "co_001",
      "userRef": "link_usr_abc",
      "unitsRequested": "2000",
      "status": "pendingReview",
      "requestedRate": {
        "baseUnitsPerVcUnit": "100",
        "capturedAt": "2024-05-01T00:00:00.000Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Approve Cashout RequestPOST

/v1/vc/cashouts/{cashoutRequestId}/approve

Approve and execute a cashout. Debits the requested units and records a conversion. Requires an Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/vc/cashouts/co_001/approve \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 89e4e214-7139-4fd9-b902-4a6f11700337"

Example Response

{
  "transactionId": "jrnl_convert_1",
  "usedBaseUnitsPerVcUnit": "100",
  "convertedBaseUnits": "200000"
}
Go to top

Reject Cashout RequestPOST

/v1/vc/cashouts/{cashoutRequestId}/reject

Reject a pending cashout request. Requires an Idempotency-Key header. Returns 204.

curl -X POST https://oncade.gg/api/v1/vc/cashouts/co_001/reject \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 9daf97ee-5150-4cb2-b7c7-251d64de600a" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "KYC pending"
}'
Go to top

Get CampaignGET

/v1/campaign/{campaignId}

Fetch campaign details, status, and balances.

curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true,
  "campaign": {
    "id": "cmp_demo",
    "name": "My Campaign",
    "environment": "test",
    "status": "started",
    "businessId": "65fa1234abcdef5678901234",
    "address": "0xabcDEFabcDEFabcDEFabcDEFabcDEFabcDEFabcd",
    "chain": "base-sepolia",
    "createdAt": "2025-09-01T12:34:56.789Z",
    "updatedAt": "2025-09-01T12:34:56.789Z",
    "totalAmountFunded": 0,
    "totalAmountPaidOut": 0,
    "availableToWithdraw": 0
  }
}
Go to top

Start CampaignPUT

/v1/campaign/{campaignId}/start

Activate the campaign. Returns 202 and enqueues a background job.

curl -X PUT https://oncade.gg/api/v1/campaign/cmp_demo/start \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 33d80ddc-f875-4954-bd97-cca4a7ca8c64"

Example Response

{
  "success": true,
  "message": "Start enqueued"
}
Go to top

Stop CampaignPUT

/v1/campaign/{campaignId}/stop

Stop the campaign. Returns 202 and enqueues a background job.

curl -X PUT https://oncade.gg/api/v1/campaign/cmp_demo/stop \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 1b4ffc8e-63f7-4c95-ba0d-be00a5a75824"

Example Response

{
  "success": true,
  "message": "Stop enqueued"
}
Go to top

Enqueue Campaign EventPOST

/v1/campaign/{campaignId}/events

Record a campaign event for a linked user, or send a one-time tip when payoutAmount is provided instead of (or with) eventCode. Returns 202.

curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/events \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 31102ace-e92a-4add-bdab-2594223b24c8" \
  -H "Content-Type: application/json" \
  -d '{
  "eventCode": "quest_complete",
  "userRef": "link_usr_123"
}'

Example Response

{
  "success": true,
  "message": "Event enqueued"
}
Go to top

List Campaign EventsGET

/v1/campaign/{campaignId}/events

Return configured campaign events.

curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/events \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true,
  "events": [
    {
      "code": "quest_complete",
      "name": "Quest Complete",
      "payoutAmount": 1000
    }
  ]
}
Go to top

Withdraw Campaign FundsPOST

/v1/campaign/{campaignId}/withdraw

Withdraw remaining funds from a stopped campaign. Returns 202.

curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/withdraw \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: d6e43a39-70b0-4358-99f0-0ad1bb87fb97"

Example Response

{
  "success": true,
  "message": "Withdrawal enqueued"
}
Go to top

Get Campaign User DetailsGET

/v1/campaign/{campaignId}/user/{userId}

Fetch a user's status within a campaign.

curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/user/user_123 \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true,
  "data": {
    "campaignId": "cmp_demo",
    "userId": "user_123",
    "status": "started",
    "environment": "test"
  }
}
Go to top

Get Campaign User EventsGET

/v1/campaign/{campaignId}/user/{userId}/events

Fetch paginated event history for a user in a campaign.

curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/user/user_123/events?limit=10&offset=0 \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true,
  "data": {
    "campaignId": "cmp_demo",
    "userId": "user_123",
    "environment": "test",
    "transactions": [
      {
        "id": "507f1f77bcf86cd799439011",
        "campaignId": "cmp_demo",
        "userRef": "user_123",
        "eventCode": "quest_complete",
        "eventName": "Quest Complete",
        "payoutAmount": 1000,
        "transactionHash": "0xabc123def456...",
        "createdAt": "2025-10-01T14:30:00.000Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 1,
      "hasMore": false
    }
  }
}
Go to top

List Campaign Linked UsersGET

/v1/campaign/{campaignId}/users

List users with an approved account link to a campaign, paginated.

curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/users?page=1&limit=20 \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "users": [
    {
      "linkId": "6614abc123",
      "userRef": "link_usr_123",
      "email": "player@example.com",
      "name": "Jane Doe",
      "linkedAt": "2026-07-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Remove Campaign Linked UserDELETE

/v1/campaign/{campaignId}/users/{userRef}

Expire a user's account link to a campaign.

curl -X DELETE https://oncade.gg/api/v1/campaign/cmp_demo/users/link_usr_123 \
  -H "Authorization: Bearer CAMPAIGN_API_KEY" \
  -H "X-Campaign-Id: CAMPAIGN_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true
}
Go to top

Get User PurchasesGET

/v1/users/{userRef}/purchases

List purchase history for a user.

curl -X GET https://oncade.gg/api/v1/users/user_123/purchases?limit=10&offset=20&type=subscription \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

[
  {
    "gameId": "game_123",
    "createdAt": "2024-03-10T14:12:01.123Z",
    "paymentProvider": "coinflow",
    "priceInCents": 1299,
    "status": "completed",
    "item": {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Founders Pass",
      "type": "subscription",
      "price": 1299
    }
  }
]
Go to top

Get User PurchaseGET

/v1/users/{userRef}/purchases/{purchaseId}

Fetch a single purchase for a user by purchase ID.

curl -X GET https://oncade.gg/api/v1/users/user_123/purchases/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "gameId": "game_123",
  "createdAt": "2024-03-10T14:12:01.123Z",
  "paymentProvider": "coinflow",
  "priceInCents": 1299,
  "status": "completed",
  "item": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Founders Pass",
    "type": "subscription",
    "price": 1299
  }
}
Go to top

Get User InfoGET

/v1/users/{userRef}

Fetch profile information for a user.

curl -X GET https://oncade.gg/api/v1/users/user_123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "userRef": "user_123",
  "email": "player@example.com",
  "profileImageUrl": "https://cdn.example.com/u/123.png",
  "subscriptions": [
    {
      "itemId": "item_456",
      "status": "Active",
      "subscriptionId": "sub_123",
      "planCode": "PREMIUM_MONTHLY",
      "planId": "plan_abc"
    }
  ]
}
Go to top

Get User SubscriptionsGET

/v1/users/{userRef}/subscriptions

Fetch all subscriptions for a user.

curl -X GET https://oncade.gg/api/v1/users/user_123/subscriptions \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "subscriptions": [
    {
      "itemId": "item_456",
      "status": "Active",
      "subscriptionId": "sub_123",
      "planCode": "PREMIUM_MONTHLY",
      "planId": "plan_abc"
    },
    {
      "itemId": "item_789",
      "status": "Canceled",
      "subscriptionId": "sub_456",
      "planCode": "BASIC_YEARLY",
      "planId": "plan_xyz"
    }
  ]
}
Go to top

Get Subscription by ItemGET

/v1/users/{userRef}/subscriptions/{itemId}

Fetch a specific subscription for a user by item ID.

curl -X GET https://oncade.gg/api/v1/users/user_123/subscriptions/item_456 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "itemId": "item_456",
  "status": "Active",
  "subscriptionId": "sub_123",
  "planCode": "PREMIUM_MONTHLY",
  "planId": "plan_abc"
}
Go to top

Cancel SubscriptionPOST

/v1/users/{userRef}/subscriptions/{itemId}/cancel

Cancel an active subscription. Works for guest accounts too. Requires an Idempotency-Key header. Dispatches Subscription.Canceled.

curl -X POST https://oncade.gg/api/v1/users/user_abc123/subscriptions/6565fade4f0d5f25af0a9ab3/cancel \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 257664f2-9862-44a2-9594-4da334578141"

Example Response

{
  "success": true,
  "subscriptionId": "sub_123"
}
Go to top

List ProductsGET

/v1/products

List products for the game. Supports filtering by status, type, creator, or keyword.

curl -X GET https://oncade.gg/api/v1/products?status=active&type=purchase&q=sword&page=1&limit=20 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "products": [
    {
      "_id": "64b10b1cec13f995e9000011",
      "gameId": "game_123",
      "environment": "test",
      "type": "purchase",
      "name": "Sword of Testing",
      "description": "Legendary blade for QA heroes.",
      "price": 100,
      "fulfillmentType": "NONE",
      "isVisible": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Get ProductGET

/v1/product/{productId}

Fetch a single product by ID.

curl -X GET https://oncade.gg/api/v1/product/64b10b1cec13f995e9000011 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "_id": "64b10b1cec13f995e9000011",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "name": "Sword of Testing",
  "description": "Legendary blade for QA heroes.",
  "baseGameRequirementText": "Requires the free base game to play.",
  "price": 100,
  "fulfillmentType": "NONE",
  "isVisible": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
Go to top

Create Product (SDK)POST

/v1/product

Create a product from your game server. Accepts USD and/or virtual currency pricing. Returns 201.

curl -X POST https://oncade.gg/api/v1/product \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 829fd828-bb43-4740-9441-72ad46c2058f" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Premium Sword",
  "type": "purchase",
  "fulfillmentType": "WEBHOOK",
  "description": "A legendary blade",
  "baseGameRequirementText": "Requires the free base game to play.",
  "price": 1500,
  "virtualCurrencyPrices": "[\n  {\n    \"currencyId\": \"cur_123\",\n    \"amount\": 100\n  }\n]",
  "perUserLimit": 1,
  "metadata": {
    "rarity": "legendary"
  }
}'

Example Response

{
  "_id": "65fa1234abcdef5678901234",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "name": "Premium Sword",
  "description": "A legendary blade",
  "baseGameRequirementText": "Requires the free base game to play.",
  "price": 1500,
  "hasUsdPrice": true,
  "virtualCurrencyPrices": [
    {
      "currencyId": "cur_123",
      "amount": 100,
      "currency": {
        "code": "GEM",
        "name": "Gems"
      }
    }
  ],
  "fulfillmentType": "WEBHOOK",
  "isVisible": true,
  "isPriceVisible": true,
  "forSale": true,
  "perUserLimit": 1,
  "status": "active",
  "creatorType": "game",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
Go to top

Update Product (SDK)PATCH

/v1/product/{productId}

Update an existing product. All fields are optional.

curl -X PATCH https://oncade.gg/api/v1/product/65fa1234abcdef5678901234 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -d '{
  "name": "Premium Sword v2",
  "baseGameRequirementText": "Requires the free base game to play.",
  "price": 1200,
  "virtualCurrencyPrices": "[\n  {\n    \"currencyId\": \"cur_123\",\n    \"amount\": 80\n  }\n]",
  "forSale": "true"
}'

Example Response

{
  "_id": "65fa1234abcdef5678901234",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "name": "Premium Sword v2",
  "description": "A legendary blade",
  "baseGameRequirementText": "Requires the free base game to play.",
  "price": 1200,
  "hasUsdPrice": true,
  "virtualCurrencyPrices": [
    {
      "currencyId": "cur_123",
      "amount": 80,
      "currency": {
        "code": "GEM",
        "name": "Gems"
      }
    }
  ],
  "fulfillmentType": "WEBHOOK",
  "isVisible": true,
  "isPriceVisible": true,
  "forSale": true,
  "perUserLimit": 1,
  "status": "active",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-02T00:00:00.000Z"
}
Go to top

Create ProductPOST

/v1/products

Create a product for the game. Returns 201.

curl -X POST https://oncade.gg/api/v1/products \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: a5ed4d8a-4cf6-4e7a-b87b-9bcc3861b337" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Test Weapon",
  "type": "purchase",
  "fulfillmentType": "WEBHOOK",
  "description": "A test weapon created from the frontend",
  "price": 1500,
  "imageUrl": "https://cdn.example.com/items/test-weapon.png",
  "perUserLimit": 2,
  "metadata": {
    "rarity": "legendary"
  }
}'

Example Response

{
  "_id": "65fa1234abcdef5678901234",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "name": "Test Weapon",
  "description": "A test weapon created from the frontend",
  "price": 1500,
  "fulfillmentType": "WEBHOOK",
  "isVisible": true,
  "isPriceVisible": true,
  "forSale": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
Go to top

Update Product Sale StatePUT

/v1/products

Enable or disable sales for an existing product.

curl -X PUT https://oncade.gg/api/v1/products \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 6785bacc-1d04-485e-b050-24c6d5743eea" \
  -H "Content-Type: application/json" \
  -d '{
  "productId": "507f1f77bcf86cd799439011",
  "forSale": "true"
}'

Example Response

{
  "_id": "507f1f77bcf86cd799439011",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "name": "Sword of Dawn",
  "price": 1500,
  "forSale": true,
  "fulfillmentType": "WEBHOOK"
}
Go to top

Create UGC ProductPOST

/v1/products/{userRef}

Create a user-generated product. Created as a hidden draft with sales disabled. Returns 201.

curl -X POST https://oncade.gg/api/v1/products/link_usr_123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: f2c4b02e-0b45-4ba0-b5e8-80107944a3ca" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "User Created Armor",
  "type": "purchase",
  "fulfillmentType": "WEBHOOK",
  "description": "Custom armor created by user",
  "price": 2000,
  "metadata": {
    "rarity": "legendary"
  },
  "imageUrl": "https://cdn.example.com/items/ugc-armor.png",
  "perUserLimit": 1
}'

Example Response

{
  "_id": "65fa1234abcdef5678901234",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "creatorType": "ugc",
  "status": "draft",
  "name": "User Created Armor",
  "description": "Custom armor created by user",
  "price": 2000,
  "imageUrl": "https://cdn.example.com/items/ugc-armor.png",
  "metadata": {
    "rarity": "legendary",
    "idempotencyKey": "ugc-armor-20240501"
  },
  "perUserLimit": 1,
  "isVisible": false,
  "isPriceVisible": true,
  "forSale": false,
  "createdAt": "2024-04-22T18:07:43.123Z",
  "updatedAt": "2024-04-22T18:07:43.123Z",
  "fulfillmentType": "WEBHOOK"
}
Go to top

Upload UGC Product ImagePOST

/v1/products/{userRef}/{productId}/image

Upload an image for a user-generated product via multipart/form-data. Requires an Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/image \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 893ca45e-d2e8-4776-8e60-8684f02fa728"

Example Response

{
  "imageUrl": "https://cdn.example.com/items/ugc-armor.png"
}
Go to top

Submit Product for ReviewPOST

/v1/products/{userRef}/{productId}/submit

Submit a user-generated product for admin review.

curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/submit \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: f1e5c862-0433-48d7-920a-805be0bfd3e5"
Go to top

Review ProductPOST

/v1/products/{userRef}/{productId}/review

Approve or decline a submitted product. On approval, you can override pricing and display settings.

curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/review \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 50debe3a-35e8-4e49-9a8e-4071fb23ca89" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approve",
  "isVisible": "true",
  "forSale": "true",
  "price": 1500,
  "virtualCurrencyPrices": "[\n  {\n    \"currencyId\": \"cur_123\",\n    \"amount\": 100\n  }\n]"
}'

Example Response

{
  "_id": "65fa1234abcdef5678901234",
  "gameId": "game_123",
  "environment": "test",
  "type": "purchase",
  "creatorType": "ugc",
  "status": "active",
  "name": "User Created Armor",
  "description": "Custom armor created by user",
  "price": 1500,
  "hasUsdPrice": true,
  "virtualCurrencyPrices": [
    {
      "currencyId": "cur_123",
      "amount": 100
    }
  ],
  "virtualCurrencyDetails": [
    {
      "_id": "cur_123",
      "code": "GEM",
      "name": "Gems"
    }
  ],
  "imageUrl": "https://cdn.example.com/items/ugc-armor.png",
  "metadata": {
    "rarity": "legendary",
    "idempotencyKey": "ugc-armor-20240501"
  },
  "perUserLimit": 1,
  "isVisible": true,
  "isPriceVisible": true,
  "forSale": true,
  "fulfillmentType": "WEBHOOK",
  "createdAt": "2024-04-22T18:07:43.123Z",
  "updatedAt": "2024-04-22T18:07:43.123Z"
}
Go to top

List Creator ProductsGET

/v1/products/{userRef}

List products created by a specific user.

curl -X GET https://oncade.gg/api/v1/products/user_123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"
Go to top

Get User BalancePOST

/v1/wallet/balance

Return wallet address and balance for a user. Requires Idempotency-Key.

curl -X POST https://oncade.gg/api/v1/wallet/balance \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 066093bd-b5ba-41e4-a4b1-394c187c80be" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "user_123"
}'

Example Response

{
  "address": "0xabcDEFabcDEFabcDEFabcDEFabcDEFabcDEFabcd",
  "balance": "1500000"
}
Go to top

Get Manage Wallet LinkPOST

/v1/wallet/manage

Generate a profile management link for a user. Requires Idempotency-Key.

curl -X POST https://oncade.gg/api/v1/wallet/manage \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: b92b1591-696d-4d6a-a46e-4cdc9233bc9c" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "user_123"
}'

Example Response

{
  "linkUrl": "https://oncade.gg/dashboard/profile"
}
Go to top

Get Wallet PurchaseGET

/v1/wallet/purchase/{purchaseId}

Fetch status and payout details for a wallet purchase.

curl -X GET https://oncade.gg/api/v1/wallet/purchase/purchase_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "data": {
    "_id": "purchase_abc123",
    "itemId": "65fa1234abcdef5678901234",
    "userId": "507f1f77bcf86cd799439011",
    "gameId": "game_123",
    "environment": "test",
    "status": "pending",
    "fulfillmentStatus": "pending",
    "priceInCents": 1000,
    "taxAmountInCents": 0,
    "feeRate": {
      "percentage": 10,
      "flat": 0
    },
    "feeName": "walletFee",
    "payouts": [
      {
        "recipient": "creator",
        "recipientAddress": "0xCreatorAddress",
        "amount": 700
      },
      {
        "recipient": "platform",
        "recipientAddress": "0xPlatformAddress",
        "amount": 300
      }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
Go to top

Initiate Virtual Currency PurchasePOST

/v1/vc/purchases

Start a virtual currency purchase. Returns 201 with the amount to debit and a link to the complete endpoint.

curl -X POST https://oncade.gg/api/v1/vc/purchases \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: b187c19b-d50e-4a07-b4e9-b319be4a856e" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "link_usr_123",
  "itemId": "65fa1234abcdef5678901234",
  "currencyId": "cur_abc123",
  "affiliateCode": "STREAMER123",
  "dealCode": "GEMS_SALE",
  "metadata": {
    "campaign": "spring"
  }
}'

Example Response

{
  "data": {
    "purchaseId": "purchase_abc123",
    "currencyId": "cur_abc123",
    "amountUnits": "800"
  }
}
Go to top

Complete Virtual Currency PurchasePOST

/v1/vc/purchases/{purchaseId}

Complete a virtual currency purchase. Debits the balance and triggers fulfillment. Idempotent via Idempotency-Key.

curl -X POST https://oncade.gg/api/v1/vc/purchases/purchase_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: db1b4584-b747-495c-8c11-67bd7b65948c"

Example Response

{
  "data": {
    "userRef": "link_usr_123",
    "purchaseId": "purchase_abc123",
    "journalId": "txn_xyz789",
    "newBalanceUnits": "9000",
    "purchase": {
      "_id": "purchase_abc123",
      "status": "completed",
      "isPaid": true,
      "fulfillmentStatus": "completed"
    }
  }
}
Go to top

Get Checkout ThemeGET

/v1/checkout/theme

Return the checkout theme for a game. Falls back to store theme colors if no game theme is set.

curl -X GET https://oncade.gg/api/v1/checkout/theme?gameId=test-game&itemId=65fa1234abcdef5678901234 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "primaryButtonColor": "#3B82F6",
  "secondaryButtonColor": "#22C55E",
  "notifyButtonColor": "#374151",
  "backgroundColor": "#1F2937",
  "borderColor": "#374151",
  "priceOverrideColor": "#4ade80",
  "logoUrl": "https://cdn.oncade.com/logos/game.png",
  "primaryFontColor": "#F9FAFB",
  "primaryButtonFontColor": "#FFFFFF",
  "secondaryButtonFontColor": "#FFFFFF",
  "lineItemsFontColor": "#D1D5DB",
  "contentLabelColor": "#9CA3AF",
  "contentTextColor": "#F9FAFB",
  "pageBackgroundColor": "#111827"
}
Go to top

Get Store Checkout URLGET

/v1/checkout/redirect

Return a storefront checkout URL for an item. Use checkoutMethod to auto-select a payment method. Returns 404/403/410 if the item is not found/visible/for sale.

curl -X GET https://oncade.gg/api/v1/checkout/redirect?gameId=test-game&itemId=65fa1234abcdef5678901234&checkoutmethod=credit \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "status": 200,
  "headers": {
    "Location": "https://oncade.gg/games/test-game/items/65fa1234abcdef5678901234?mode=api&checkoutmethod=credit"
  },
  "body": {
    "url": "https://oncade.gg/games/test-game/items/65fa1234abcdef5678901234?mode=api&checkoutmethod=credit"
  }
}
Go to top

Create Checkout GrantPOST

/v1/checkout/grants

Create a signed checkout grant so players can purchase without authenticating on Oncade first. Returns a one-time checkout URL (expires after 2 hours). If no userRef is provided, one is generated or looked up by email. The same email always resolves to the same userRef per game.

curl -X POST https://oncade.gg/api/v1/checkout/grants \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 27644f4b-a224-472f-9a48-1e776d1fa81e" \
  -H "Content-Type: application/json" \
  -d '{
  "itemId": "65fa1234abcdef5678901234",
  "email": "player@example.com",
  "checkoutMetadata": {
    "orderId": "game-order-12345",
    "playerId": "player-abc",
    "source": "in-game-store"
  },
  "customMessage": "Thank you for your purchase! Your items will be delivered within 24 hours."
}'

Example Response

{
  "checkoutUrl": "https://oncade.gg/checkout/grant?checkoutGrantId=550e8400-e29b-41d4-a716-446655440000&sig=abc123...",
  "userRef": "user_abc123def456"
}
Go to top

List Split TemplatesGET

/v1/split-templates

List non-archived split templates for the business, newest first.

curl -X GET https://oncade.gg/api/v1/split-templates \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "templates": [
    {
      "_id": "64b10b1cec13f995e9000011",
      "name": "Team Revenue Split",
      "description": "Default split for team revenue sharing",
      "businessId": "64b10b1cec13f995e9000012",
      "createdBy": "usr_123",
      "recipients": [
        {
          "email": "dev1@example.com",
          "name": "Developer 1",
          "percentage": 50
        },
        {
          "email": "dev2@example.com",
          "name": "Developer 2",
          "percentage": 30
        },
        {
          "email": "dev3@example.com",
          "name": "Developer 3",
          "percentage": 20
        }
      ],
      "isArchived": false,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}
Go to top

Create Split TemplatePOST

/v1/split-templates

Create a split template. In percentage mode, recipient percentages must sum to 100%; in fixed mode, recipients carry a fixed amount instead. Names must be unique per business. Returns 201.

curl -X POST https://oncade.gg/api/v1/split-templates \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 8327c8c6-7175-4443-b93e-71f80997b1d3" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Team Revenue Split",
  "mode": "percentage",
  "description": "Default split for team revenue sharing",
  "recipients": "[\n  {\n    \"email\": \"dev1@example.com\",\n    \"name\": \"Developer 1\",\n    \"percentage\": 50\n  },\n  {\n    \"email\": \"dev2@example.com\",\n    \"name\": \"Developer 2\",\n    \"percentage\": 30\n  },\n  {\n    \"email\": \"dev3@example.com\",\n    \"name\": \"Developer 3\",\n    \"percentage\": 20\n  }\n]"
}'

Example Response

{
  "_id": "64b10b1cec13f995e9000011",
  "name": "Team Revenue Split",
  "description": "Default split for team revenue sharing",
  "businessId": "64b10b1cec13f995e9000012",
  "createdBy": "usr_123",
  "mode": "percentage",
  "recipients": [
    {
      "email": "dev1@example.com",
      "name": "Developer 1",
      "percentage": 50
    },
    {
      "email": "dev2@example.com",
      "name": "Developer 2",
      "percentage": 30
    },
    {
      "email": "dev3@example.com",
      "name": "Developer 3",
      "percentage": 20
    }
  ],
  "isArchived": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
Go to top

Get Split TemplateGET

/v1/split-templates/{templateId}

Fetch a split template by ID.

curl -X GET https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "_id": "64b10b1cec13f995e9000011",
  "name": "Team Revenue Split",
  "description": "Default split for team revenue sharing",
  "businessId": "64b10b1cec13f995e9000012",
  "createdBy": "usr_123",
  "recipients": [
    {
      "email": "dev1@example.com",
      "name": "Developer 1",
      "percentage": 50
    },
    {
      "email": "dev2@example.com",
      "name": "Developer 2",
      "percentage": 30
    },
    {
      "email": "dev3@example.com",
      "name": "Developer 3",
      "percentage": 20
    }
  ],
  "isArchived": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
Go to top

Update Split TemplatePUT

/v1/split-templates/{templateId}

Update a split template. All fields optional. If recipients change, percentages must still sum to 100% in percentage mode.

curl -X PUT https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 2b57ba86-828f-431a-91ce-b4c0a3a657a4" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated Team Split",
  "recipients": "[\n  {\n    \"email\": \"dev1@example.com\",\n    \"name\": \"Developer 1\",\n    \"percentage\": 60\n  },\n  {\n    \"email\": \"dev2@example.com\",\n    \"name\": \"Developer 2\",\n    \"percentage\": 40\n  }\n]"
}'

Example Response

{
  "_id": "64b10b1cec13f995e9000011",
  "name": "Updated Team Split",
  "description": "Default split for team revenue sharing",
  "businessId": "64b10b1cec13f995e9000012",
  "createdBy": "usr_123",
  "mode": "percentage",
  "recipients": [
    {
      "email": "dev1@example.com",
      "name": "Developer 1",
      "percentage": 60
    },
    {
      "email": "dev2@example.com",
      "name": "Developer 2",
      "percentage": 40
    }
  ],
  "isArchived": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-02T00:00:00.000Z"
}
Go to top

Get Split Template Redirect URLGET

/v1/split-templates/{templateId}/redirect

Return a redirect URL to the DevPortal distribution page with this template pre-loaded.

curl -X GET https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011/redirect?amount=1000 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "url": "https://dev.oncade.gg/dashboard/business/team-payouts/distribute?templateId=64b10b1cec13f995e9000011&amount=1000"
}
Go to top

Create Ghost UserPOST

/v1/platform/vc/users

Create a ghost user for virtual currency operations. If an email is provided, the call is idempotent — the same email always resolves to the same user. Returns 409 if the email belongs to an existing authenticated user. Requires platform API key with vc:user:create scope.

curl -X POST https://oncade.gg/api/v1/platform/vc/users \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: e8b9498c-0d93-4370-b67d-0ae3b5f516f7" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "player@example.com"
}'

Example Response

{
  "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d"
}
Go to top

Get User VC Balance (Platform)GET

/v1/platform/vc/balances

Fetch a user's virtual currency balance. Requires platform API key with vc:balance:read scope, X-Target-Business-Id, and X-Game-Id headers.

curl -X GET https://oncade.gg/api/v1/platform/vc/balances?currencyId=cur_123&userId=pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "currencyId": "cur_123",
  "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "balanceUnits": "500",
  "updatedAt": "2024-05-01T00:00:00.000Z"
}
Go to top

Credit VC Balance (Platform)POST

/v1/platform/vc/credits

Credit virtual currency to a user via platform API key. Requires vc:credit scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.

curl -X POST https://oncade.gg/api/v1/platform/vc/credits \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 1f615df7-3161-4df4-a73e-a3e29bf6d706" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "amountUnits": "500",
  "orderId": "stripe-order-123"
}'

Example Response

{
  "journalId": "jrnl_002",
  "newBalanceUnits": "1500"
}
Go to top

Debit VC Balance (Platform)POST

/v1/platform/vc/debits

Debit virtual currency from a user via platform API key. Requires vc:debit scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.

curl -X POST https://oncade.gg/api/v1/platform/vc/debits \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 3bdbc540-0ff7-4873-bbb3-44b858ae408f" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "amountUnits": "250",
  "reason": "refund"
}'

Example Response

{
  "journalId": "jrnl_003",
  "newBalanceUnits": "1250"
}
Go to top

Batch VC Transfer (Platform)POST

/v1/platform/vc/batch

Atomically debit one user and distribute to multiple recipients via platform API key. Requires vc:batch scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.

curl -X POST https://oncade.gg/api/v1/platform/vc/batch \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: eb17d10e-d085-4d43-bbe9-8e9d91e7e383" \
  -H "Content-Type: application/json" \
  -d '{
  "currencyId": "cur_123",
  "sourceUserId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "recipients": "[\n  {\n    \"userId\": \"pvu_b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e\",\n    \"amountUnits\": \"100\",\n    \"description\": \"Winner payout\"\n  },\n  {\n    \"toPool\": true,\n    \"amountUnits\": \"25\",\n    \"description\": \"Platform fee\"\n  }\n]"
}'

Example Response

{
  "journalId": "jrnl_batch_001",
  "newBalanceUnits": "375"
}
Go to top

Purchase Item with VC (Platform)POST

/v1/platform/vc/purchases

Purchase an item using virtual currency on behalf of a user. Debits the user's balance and records the purchase. Supports idempotency — replaying the same Idempotency-Key returns the original result. Requires platform API key with vc:purchase scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.

curl -X POST https://oncade.gg/api/v1/platform/vc/purchases \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: e43eaa29-ee8e-4c95-9e6c-961e930fca24" \
  -H "Content-Type: application/json" \
  -d '{
  "itemId": "507f1f77bcf86cd799439011",
  "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "currencyId": "507f1f77bcf86cd799439022",
  "quantity": 1
}'

Example Response

{
  "purchaseId": "507f1f77bcf86cd799439033",
  "journalId": "jrnl_004",
  "totalAmountUnits": "500",
  "newBalanceUnits": "1500",
  "item": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Gold Sword"
  }
}
Go to top

List User Purchases (Platform)GET

/v1/platform/vc/users/{userRef}/purchases

List completed virtual currency purchases for a user. Supports pagination and filtering by game, currency, and date range. Requires platform API key with vc:purchase:read scope, X-Target-Business-Id, and X-Game-Id headers.

curl -X GET https://oncade.gg/api/v1/platform/vc/users/pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d/purchases?page=1&limit=20 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "items": [
    {
      "_id": "507f1f77bcf86cd799439033",
      "platformUserId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
      "gameId": "game_001",
      "itemId": "507f1f77bcf86cd799439011",
      "itemName": "Gold Sword",
      "currencyId": "507f1f77bcf86cd799439022",
      "unitPrice": "500",
      "quantity": 1,
      "totalAmountUnits": "500",
      "journalId": "jrnl_004",
      "status": "completed",
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

List Business Linked Users (Platform)GET

/v1/platform/business/users

List users linked to the target business (paginated), or search them by email/name with ?search=. userRefs are env-prefixed. Requires platform API key with business:users:link:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/business/users?page=1&limit=20 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "users": [
    {
      "linkId": "507f1f77bcf86cd799439044",
      "userRef": "obu_test_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
      "email": "player@example.com",
      "name": "Player One",
      "linkedAt": "2026-01-15T10:00:00.000Z",
      "environment": "test"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Business User Wallet Balance (Platform)GET

/v1/platform/business/users/{userRef}/wallet/balance

Retrieve the wallet address and balance for a business-linked user. The userRef must be an obu_ or obu_test_ reference. Requires platform API key with business:users:link:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/business/users/obu_test_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d/wallet/balance \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "address": "0x1234...abcd",
  "balance": "10.50"
}
Go to top

Business User Compliance Status (Platform)GET

/v1/platform/business/users/{userRef}/compliance

Check the KYC compliance status of a business-linked user. Returns a normalized status across providers. When the user has not completed KYC, includes a kycUrl the platform can redirect the user to. The userRef must be an obu_ or obu_test_ reference. Requires platform API key with business:users:link:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/business/users/obu_test_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d/compliance \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "userRef": "obu_test_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "status": "not_started",
  "kycUrl": "https://app.oncade.xyz/dashboard/profile"
}
Go to top

Assign Business User to Campaign (Platform)POST

/v1/platform/business/users/{userRef}/campaigns/{campaignId}/assign

Assign a business-linked user to a platform-owned campaign. Automatically creates a campaign link session and returns a campaign-scoped userRef (pvu_…). The campaign must belong to the target business and match the API key environment. Requires platform API key with business:users:link:read scope and X-Target-Business-Id header.

curl -X POST https://oncade.gg/api/v1/platform/business/users/obu_test_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d/campaigns/camp_xyz/assign \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: bc9c748a-a8aa-4bf7-be1a-a98297dad235"

Example Response

{
  "campaignUserRef": "c9d8e7f6-a1b2-4c3d-8e5f-6a7b8c9d0e1f",
  "email": "player@example.com",
  "assigned": true
}
Go to top

Create Business (Platform)POST

/v1/platform/business

Create a new business with members (exactly one must be the owner with the ADMIN role) and, optionally, an auto-grant of scopes for this platform. Requires platform API key with business:create scope and an Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/business \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 6106117b-9882-4c38-a812-af25cfd76927" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Games",
  "members": "[\n  {\n    \"email\": \"owner@acme.com\",\n    \"roles\": [\n      \"ADMIN\"\n    ],\n    \"isOwner\": true\n  }\n]"
}'

Example Response

{
  "business": {
    "_id": "64f10b1cec13f995e9000001",
    "name": "Acme Games",
    "canSellItems": false,
    "walletProvider": "privy"
  },
  "members": [
    {
      "userId": "64a10b1cec13f995e9000099",
      "email": "owner@acme.com",
      "roles": [
        "ADMIN"
      ],
      "isOwner": true
    }
  ],
  "links": {
    "home": "https://dev.oncade.gg/dashboard/business",
    "kyb": "https://pay.oncade.xyz/...",
    "signIn": "https://oncade.gg/sign-in"
  }
}
Go to top

Get Target Business (Platform)GET

/v1/platform/business

Fetch details, readiness status, and whitebox links for the target business. Requires platform API key with business:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/business \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "_id": "64f10b1cec13f995e9000001",
  "name": "Acme Games",
  "canSellItems": true,
  "readiness": {
    "ready": true,
    "verifiedViaOwnerKyc": false,
    "steps": {
      "payoutWallet": "complete",
      "address": "complete",
      "kybVerification": "complete"
    },
    "setupUrl": "https://dev.oncade.gg/dashboard/business/setup"
  },
  "links": {
    "home": "https://dev.oncade.gg/dashboard/business",
    "kyb": "https://pay.oncade.xyz/...",
    "signIn": "https://oncade.gg/sign-in"
  }
}
Go to top

Update Target Business (Platform)PATCH

/v1/platform/business

Update the target business's details (name, logo, payout wallet, address, invoice recipients). Changing payoutWallet repoints the business's Bridge collection account. Requires platform API key with business:update scope and X-Target-Business-Id header.

curl -X PATCH https://oncade.gg/api/v1/platform/business \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -d '{
  "name": "Acme Games Inc."
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000001",
  "name": "Acme Games Inc.",
  "canSellItems": true
}
Go to top

Business Readiness (Platform)GET

/v1/platform/business/readiness

Check whether the target business is ready to receive payouts (payout wallet, address, and KYB verification steps). If KYB is incomplete, links.kyb points to the pay-app KYB flow. Requires platform API key with business:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/business/readiness \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "ready": false,
  "steps": {
    "payoutWallet": "complete",
    "address": "incomplete",
    "kybVerification": "pending"
  },
  "links": {
    "home": "https://dev.oncade.gg/dashboard/business",
    "kyb": "https://pay.oncade.xyz/...",
    "signIn": "https://oncade.gg/sign-in"
  }
}
Go to top

Business Wallet Balance (Platform)GET

/v1/platform/business/wallet-balance

Get the USDC wallet balance for the target business, resolving business.payoutWallet then falling back to the owner's smart wallet address. Requires platform API key with business:wallet:balance scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/business/wallet-balance \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "address": "0x1234...abcd",
  "balance": "1234.56"
}
Go to top

List Campaigns (Platform)GET

/v1/platform/campaigns

List campaigns created by this platform for the target business. Requires platform API key with campaign:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/campaigns \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "campaigns": [
    {
      "campaignId": "camp_abc123",
      "name": "Summer Promo",
      "environment": "live",
      "address": "0x1234...",
      "status": "active",
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ],
  "total": 1
}
Go to top

Create Campaign (Platform)POST

/v1/platform/campaigns

Create a new campaign for the target business. A payout contract is deployed automatically on-chain using the target business's resolved payout wallet as owner; chain (Base vs Base Sepolia) is determined by the platform's environment. Requires platform API key with campaign:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/campaigns \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 426afeae-bf29-46da-bdef-ee8fe7919111" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Summer Promo",
  "events": "[\n  {\n    \"code\": \"signup\",\n    \"name\": \"Sign Up\",\n    \"payoutAmount\": 1\n  }\n]"
}'

Example Response

{
  "campaignId": "camp_abc123",
  "name": "Summer Promo",
  "environment": "live",
  "address": "0x1234...",
  "status": "active",
  "createdAt": "2026-06-01T00:00:00.000Z"
}
Go to top

Get Campaign (Platform)GET

/v1/platform/campaigns/{campaignId}

Get details of a campaign created by this platform, including on-chain status and balance. Requires platform API key with campaign:read scope.

curl -X GET https://oncade.gg/api/v1/platform/campaigns/camp_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "campaignId": "camp_abc123",
  "name": "Summer Promo",
  "environment": "live",
  "address": "0x1234...",
  "webhookUrl": "https://example.com/webhook",
  "status": "active",
  "balance": {
    "totalFunded": 1000,
    "totalPaidOut": 250,
    "available": 750
  }
}
Go to top

Update Campaign (Platform)PATCH

/v1/platform/campaigns/{campaignId}

Update a campaign created by this platform. Requires platform API key with campaign:update scope and Idempotency-Key header.

curl -X PATCH https://oncade.gg/api/v1/platform/campaigns/camp_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -d '{
  "name": "Summer Promo v2"
}'

Example Response

{
  "campaignId": "camp_abc123",
  "name": "Summer Promo v2",
  "environment": "live",
  "address": "0x1234..."
}
Go to top

Delete Campaign (Platform)DELETE

/v1/platform/campaigns/{campaignId}

Permanently delete a campaign created by this platform. Requires platform API key with campaign:delete scope. Returns 204 No Content.

curl -X DELETE https://oncade.gg/api/v1/platform/campaigns/camp_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

null
Go to top

Start Campaign (Platform)PUT

/v1/platform/campaigns/{campaignId}/start

Start (activate) a campaign on-chain. Requires platform API key with campaign:start scope.

curl -X PUT https://oncade.gg/api/v1/platform/campaigns/camp_abc123/start \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: f1ba43aa-5d15-4f5f-9629-820fa84ff800"

Example Response

{
  "success": true,
  "message": "Start enqueued"
}
Go to top

Stop Campaign (Platform)PUT

/v1/platform/campaigns/{campaignId}/stop

Stop (deactivate) a campaign on-chain. Requires platform API key with campaign:stop scope.

curl -X PUT https://oncade.gg/api/v1/platform/campaigns/camp_abc123/stop \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 3aadc395-0be0-4beb-aa4b-a96cdff1af95"

Example Response

{
  "success": true,
  "message": "Stop enqueued"
}
Go to top

Record Campaign Event (Platform)POST

/v1/platform/campaigns/{campaignId}/events

Record a campaign event for a user (resolved from userRef) and trigger its configured payout, or send a one-time tip when payoutAmount is provided directly. Requires platform API key with campaign:events:create scope.

curl -X POST https://oncade.gg/api/v1/platform/campaigns/camp_abc123/events \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: dcd77717-9f32-413b-9620-6f963b02590b" \
  -H "Content-Type: application/json" \
  -d '{
  "eventCode": "signup",
  "userRef": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d"
}'

Example Response

{
  "success": true,
  "message": "Event enqueued"
}
Go to top

List Campaign Linked Users (Platform)GET

/v1/platform/campaigns/{campaignId}/users

List users with an approved account link to a campaign, paginated. Requires platform API key with campaign:users:link:read scope.

curl -X GET https://oncade.gg/api/v1/platform/campaigns/camp_abc123/users?page=1&limit=20 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "users": [
    {
      "linkId": "6614abc123",
      "userRef": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
      "email": "player@example.com",
      "name": "Jane Doe",
      "linkedAt": "2026-07-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Campaign User Wallet Balance (Platform)GET

/v1/platform/campaigns/{campaignId}/users/{userRef}/wallet/balance

Get the USDC wallet balance for a user linked to a campaign. Requires platform API key with campaign:users:wallet:read scope.

curl -X GET https://oncade.gg/api/v1/platform/campaigns/camp_abc123/users/pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d/wallet/balance \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "address": "0x1234...abcd",
  "balance": "12.34"
}
Go to top

Campaign Payout Wallet Balance (Platform)GET

/v1/platform/campaigns/{campaignId}/payout-wallet/balance

Get the USDC balance of the campaign's associated business payout wallet, falling back to the business owner's smart wallet. Requires platform API key with campaign:payout-wallet:balance scope.

curl -X GET https://oncade.gg/api/v1/platform/campaigns/camp_abc123/payout-wallet/balance \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "address": "0x1234...abcd",
  "balance": "1234.56"
}
Go to top

Create Campaign Fund Session (Platform)POST

/v1/platform/campaigns/{campaignId}/fund-sessions

Create (or idempotently return an existing pending) hosted pay-page session for funding a campaign's on-chain balance. Requires platform API key with campaign:funds:create scope and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/campaigns/camp_abc123/fund-sessions \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 9901a041-1174-43fb-8593-c0729425c5e0"

Example Response

{
  "sessionKey": "fs_abc123",
  "url": "https://pay.oncade.xyz/platform/plat_xyz/biz_123/fund-campaign?session=fs_abc123",
  "expiresAt": "2026-07-18T15:00:00.000Z"
}
Go to top

Get Campaign Fund Session (Platform)GET

/v1/platform/campaigns/{campaignId}/fund-sessions/{sessionHandle}

Get the status of a campaign fund session. Requires platform API key with campaign:funds:read scope.

curl -X GET https://oncade.gg/api/v1/platform/campaigns/camp_abc123/fund-sessions/fs_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "sessionKey": "fs_abc123",
  "url": "https://pay.oncade.xyz/...",
  "status": "pending",
  "campaignId": "camp_abc123",
  "createdAt": "2026-07-18T14:00:00.000Z",
  "expiresAt": "2026-07-18T15:00:00.000Z"
}
Go to top

Revoke Campaign Fund Session (Platform)DELETE

/v1/platform/campaigns/{campaignId}/fund-sessions/{sessionHandle}

Cancel a still-pending campaign fund session. Requires platform API key with campaign:funds:create scope.

curl -X DELETE https://oncade.gg/api/v1/platform/campaigns/camp_abc123/fund-sessions/fs_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true
}
Go to top

List Distributions (Platform)GET

/v1/platform/distributions

List distributions created by this platform for the target business, paginated and optionally filtered by status. Requires platform API key with distribution:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/distributions \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "distributions": [
    {
      "_id": "64f10b1cec13f995e9000011",
      "businessId": "64f10b1cec13f995e9000001",
      "totalAmountCents": 10000,
      "status": "pending",
      "currency": "USD",
      "createdAt": "2026-07-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}
Go to top

Create Distribution (Platform)POST

/v1/platform/distributions

Create a distribution for the target business, either from a saved split template (templateId) or a one-time recipient list. Requires platform API key with distribution:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/distributions \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 3f6f2e9a-f22b-43ba-9855-e8084f0519b3" \
  -H "Content-Type: application/json" \
  -d '{
  "recipients": "[\n  {\n    \"email\": \"player@example.com\",\n    \"percentage\": 100\n  }\n]",
  "totalAmountCents": 10000
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000011",
  "businessId": "64f10b1cec13f995e9000001",
  "totalAmountCents": 10000,
  "status": "pending",
  "currency": "USD"
}
Go to top

Distribution Fee Preview (Platform)GET

/v1/platform/distributions/fee-preview

Preview the auto-applied distribution fee and the target business's recipient-pays-fee defaults before creating a distribution. Requires platform API key with distribution:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/distributions/fee-preview \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "fees": [
    {
      "label": "Oncade fee",
      "percentage": 2.5,
      "flat": 0,
      "feeType": "flat_rate_plus_percentage"
    }
  ],
  "recipientPaysPercentage": true,
  "recipientPaysPlatformFeePercentage": true
}
Go to top

Create Distribution Fund Session (Platform)POST

/v1/platform/distributions/{distributionId}/fund-sessions

Create (or idempotently return an existing pending) hosted pay-page session for funding a pending distribution. Requires platform API key with distribution:funds:create scope and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/distributions/64f10b1cec13f995e9000011/fund-sessions \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 19aa2b6b-e0ab-4b2b-b2e2-f8f1609b5ca2"

Example Response

{
  "sessionKey": "fs_abc123",
  "url": "https://pay.oncade.gg/platform/plat_xyz/biz_123/fund-distribution?session=fs_abc123",
  "expiresAt": "2026-07-18T15:00:00.000Z"
}
Go to top

Get Distribution Fund Session (Platform)GET

/v1/platform/distributions/{distributionId}/fund-sessions/{sessionHandle}

Get the status of a distribution fund session. Requires platform API key with distribution:funds:read scope.

curl -X GET https://oncade.gg/api/v1/platform/distributions/64f10b1cec13f995e9000011/fund-sessions/fs_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "sessionKey": "fs_abc123",
  "url": "https://pay.oncade.gg/...",
  "status": "pending",
  "distributionId": "64f10b1cec13f995e9000011",
  "amountUsdc": 100,
  "createdAt": "2026-07-18T14:00:00.000Z",
  "expiresAt": "2026-07-18T15:00:00.000Z"
}
Go to top

Revoke Distribution Fund Session (Platform)DELETE

/v1/platform/distributions/{distributionId}/fund-sessions/{sessionHandle}

Cancel a still-pending distribution fund session. Requires platform API key with distribution:funds:create scope.

curl -X DELETE https://oncade.gg/api/v1/platform/distributions/64f10b1cec13f995e9000011/fund-sessions/fs_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "success": true
}
Go to top

Create Bulk Gift Records (Platform)POST

/v1/platform/gifts/bulk

Create gift-vault database records for recipients without wallets yet, using pre-computed vault/merkle/claim values supplied by the caller's own contract-sdk step. Requires platform API key with gift:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/gifts/bulk \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 3841504a-0d60-4ed7-b1e1-37df854a17a2" \
  -H "Content-Type: application/json" \
  -d '{
  "senderUserId": "64a10b1cec13f995e9000099",
  "senderWalletAddress": "0x1234...abcd",
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "recipients": "[\n  {\n    \"email\": \"player@example.com\",\n    \"name\": \"Jane Doe\",\n    \"amountCents\": 5000,\n    \"vaultAddress\": \"0xabc...\",\n    \"rootHash\": \"0xdef...\",\n    \"claimCode\": \"CLAIM123\",\n    \"giftConfig\": {}\n  }\n]"
}'

Example Response

{
  "success": true,
  "result": {
    "gifts": [
      {
        "giftId": "64f...",
        "email": "player@example.com",
        "amountCents": 5000,
        "claimUrl": "https://oncade.gg/claim/CLAIM123"
      }
    ],
    "totalAmount": "5000000",
    "successCount": 1,
    "failedCount": 0,
    "errors": []
  }
}
Go to top

Mark Gifts Funded (Platform)POST

/v1/platform/gifts/mark-funded

Mark a batch of gifts as funded after the caller's own on-chain funding transaction, and send claim emails to recipients. Updates the parent distribution's status. Requires platform API key with gift:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/gifts/mark-funded \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: d1f082d5-864f-42e2-8d57-07043be8f858" \
  -H "Content-Type: application/json" \
  -d '{
  "giftData": "[\n  {\n    \"giftId\": \"64f...\",\n    \"claimCode\": \"CLAIM123\"\n  }\n]",
  "transactionHash": "0xabc123...",
  "distributionId": "64f10b1cec13f995e9000011"
}'

Example Response

{
  "success": true,
  "result": {
    "updatedCount": 1,
    "emailsSent": 1,
    "emailsFailed": 0,
    "totalFundedCents": 5000
  }
}
Go to top

List Active Grants (Platform)GET

/v1/platform/grants

List all active grants for this platform (businesses that have opted in to share access). Requires platform API key with platform.grant:manage scope.

curl -X GET https://oncade.gg/api/v1/platform/grants \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "grants": [
    {
      "_id": "64f10b1cec13f995e9000031",
      "platformId": "plat_001",
      "businessId": "64f10b1cec13f995e9000001",
      "grantedScopes": [
        "invoice:read",
        "invoice:create"
      ],
      "status": "active",
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ],
  "total": 1
}
Go to top

Revoke Grant (Platform)POST

/v1/platform/grants/{grantId}/revoke

Revoke an active grant and clear any existing invite for the same business, allowing a new invite with different scopes to be sent. Requires platform API key with platform.grant:manage scope.

curl -X POST https://oncade.gg/api/v1/platform/grants/64f10b1cec13f995e9000031/revoke \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 580a1c71-b0d2-41f7-9c77-ae775d74a9bf"

Example Response

{
  "success": true,
  "message": "Grant revoked. You can now send a new invite with updated permissions."
}
Go to top

List Invites (Platform)GET

/v1/platform/invites

List all invites sent by this platform, in any status. Requires platform API key with platform.invite:manage scope.

curl -X GET https://oncade.gg/api/v1/platform/invites \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "invites": [
    {
      "_id": "64f10b1cec13f995e9000041",
      "platformId": "plat_001",
      "businessId": "64f10b1cec13f995e9000001",
      "requestedScopes": [
        "invoice:read"
      ],
      "status": "pending",
      "createdAt": "2026-07-01T00:00:00.000Z",
      "expiresAt": "2026-07-15T00:00:00.000Z"
    }
  ],
  "total": 1
}
Go to top

Send Invite (Platform)POST

/v1/platform/invites

Send an invite to a business requesting access with specified scopes. Remains pending until the business accepts or rejects it. Requires platform API key with platform.invite:manage scope and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/invites \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 69500c27-ecea-44d0-a111-26f200fc3065" \
  -H "Content-Type: application/json" \
  -d '{
  "businessId": "64f10b1cec13f995e9000001",
  "requestedScopes": "[\n  \"invoice:read\",\n  \"invoice:create\"\n]"
}'

Example Response

{
  "inviteId": "64f10b1cec13f995e9000041",
  "platformId": "plat_001",
  "businessId": "64f10b1cec13f995e9000001",
  "requestedScopes": [
    "invoice:read",
    "invoice:create"
  ],
  "status": "pending"
}
Go to top

Cancel Invite (Platform)POST

/v1/platform/invites/{inviteId}/cancel

Cancel an invite sent by this platform. Requires platform API key with platform.invite:manage scope.

curl -X POST https://oncade.gg/api/v1/platform/invites/64f10b1cec13f995e9000041/cancel \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: bd00dba7-0d74-484b-bd70-3e36211ed854"

Example Response

{
  "success": true,
  "message": "Invite cancelled successfully"
}
Go to top

List Invoices (Platform)GET

/v1/platform/invoices

List invoices for the target business, paginated and optionally filtered by status. Requires platform API key with invoice:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/invoices \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "invoices": [
    {
      "_id": "64f10b1cec13f995e9000051",
      "invoiceNumber": "INV-0001",
      "status": "draft",
      "total": 100,
      "currency": "USD",
      "links": {
        "invoice": "https://pay.oncade.xyz/i/plat_001/biz_123/64f10b1cec13f995e9000051"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Create Invoice (Platform)POST

/v1/platform/invoices

Create an invoice for the target business, addressed to either an email or another Oncade business (recipientBusinessId). Requires platform API key with invoice:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/invoices \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 1e83f80e-f4cd-4452-91b1-3a36e44a4888" \
  -H "Content-Type: application/json" \
  -d '{
  "date": "2026-07-18",
  "receiverEmail": "billing@acme.com",
  "payToTarget": "BUSINESS",
  "items": "[\n  {\n    \"description\": \"Consulting\",\n    \"quantity\": 1,\n    \"rate\": 100\n  }\n]"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000051",
  "invoiceNumber": "INV-0001",
  "status": "draft",
  "total": 100,
  "currency": "USD",
  "links": {
    "invoice": "https://pay.oncade.xyz/i/plat_001/biz_123/64f10b1cec13f995e9000051"
  }
}
Go to top

Get Invoice (Platform)GET

/v1/platform/invoices/{invoiceId}

Get a single invoice by ID. Requires platform API key with invoice:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/invoices/64f10b1cec13f995e9000051 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "_id": "64f10b1cec13f995e9000051",
  "invoiceNumber": "INV-0001",
  "status": "draft",
  "total": 100,
  "currency": "USD"
}
Go to top

Update Invoice (Platform)PUT

/v1/platform/invoices/{invoiceId}

Update a non-terminal invoice (draft/sent/processing). Paid and cancelled invoices cannot be modified, and status changes must follow valid transitions. Requires platform API key with invoice:update scope and X-Target-Business-Id header.

curl -X PUT https://oncade.gg/api/v1/platform/invoices/64f10b1cec13f995e9000051 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: be37c57c-1bb3-412c-9620-bacbf27aaa7c" \
  -H "Content-Type: application/json" \
  -d '{
  "date": "2026-07-18",
  "items": "[\n  {\n    \"description\": \"Consulting\",\n    \"quantity\": 1,\n    \"rate\": 100\n  }\n]",
  "status": "sent"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000051",
  "invoiceNumber": "INV-0001",
  "status": "sent",
  "total": 100
}
Go to top

Cancel Invoice (Platform)POST

/v1/platform/invoices/{invoiceId}/cancel

Cancel a draft or sent invoice. Requires platform API key with invoice:cancel scope and X-Target-Business-Id header.

curl -X POST https://oncade.gg/api/v1/platform/invoices/64f10b1cec13f995e9000051/cancel \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 4a0ae322-598b-4518-896a-c7a3a4c327bb"

Example Response

{
  "_id": "64f10b1cec13f995e9000051",
  "status": "cancelled"
}
Go to top

Send Invoice (Platform)POST

/v1/platform/invoices/{invoiceId}/send

Transition a draft (or processing) invoice to sent, optionally emailing the recipient. Requires platform API key with invoice:send scope and X-Target-Business-Id header.

curl -X POST https://oncade.gg/api/v1/platform/invoices/64f10b1cec13f995e9000051/send \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 99c66833-5930-477c-9789-add7316d1343"

Example Response

{
  "_id": "64f10b1cec13f995e9000051",
  "status": "sent",
  "emailSuppressed": false
}
Go to top

Lookup Emails (Platform)POST

/v1/platform/lookup-emails

Check which of a list of emails already have an Oncade account with a wallet, e.g. before creating a distribution. Exposes only a boolean per email, never other user data. Requires platform API key with lookup:emails scope and X-Target-Business-Id header.

curl -X POST https://oncade.gg/api/v1/platform/lookup-emails \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: b774262d-0794-4999-a23a-08e068c5f9da" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": "[\n  \"player@example.com\",\n  \"nobody@example.com\"\n]"
}'

Example Response

{
  "results": [
    {
      "email": "player@example.com",
      "hasAccount": true
    },
    {
      "email": "nobody@example.com",
      "hasAccount": false
    }
  ]
}
Go to top

Get Current Platform (Platform)GET

/v1/platform/me

Get the current platform's information, including approved and pending scopes and the calling key's active/requested scopes. Requires platform API key with platform:read scope.

curl -X GET https://oncade.gg/api/v1/platform/me \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "platformId": "plat_001",
  "name": "Acme Platform",
  "status": "active",
  "approvedScopes": [
    "invoice:read",
    "invoice:create"
  ],
  "pendingScopes": [],
  "keyInfo": {
    "keyId": "key_abc123",
    "environment": "live",
    "activeScopes": [
      "invoice:read"
    ],
    "requestedScopes": [
      "invoice:read",
      "invoice:create"
    ]
  }
}
Go to top

Request Platform Scopes (Platform)POST

/v1/platform/me/scopes

Request new scopes for the platform. Creates a scope request for admin review; in test environment scopes are auto-approved. Requires platform API key with platform.scope:request scope.

curl -X POST https://oncade.gg/api/v1/platform/me/scopes \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: ed1c5a1e-f5ef-4ccf-9f9d-506641d377b7" \
  -H "Content-Type: application/json" \
  -d '{
  "scopes": "[\n  \"distribution:create\"\n]"
}'

Example Response

{
  "requestId": "64f10b1cec13f995e9000071",
  "requestedScopes": [
    "distribution:create"
  ],
  "status": "pending",
  "platform": {
    "approvedScopes": [
      "invoice:read"
    ],
    "pendingScopes": [
      "distribution:create"
    ]
  }
}
Go to top

List Platform API Keys (Platform)GET

/v1/platform/me/keys

List all API keys for this platform with computed statuses. Requires platform API key with platform.key:manage scope.

curl -X GET https://oncade.gg/api/v1/platform/me/keys \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "keys": [
    {
      "keyId": "key_abc123",
      "platformId": "plat_001",
      "environment": "live",
      "requestedScopes": [
        "invoice:read"
      ],
      "activeScopes": [
        "invoice:read"
      ],
      "status": "active",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}
Go to top

Create Platform API Key (Platform)POST

/v1/platform/me/keys

Create a new API key for this platform. In test environment, requested scopes are auto-approved. The raw key value is only returned once, at creation. Requires platform API key with platform.key:manage scope and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/me/keys \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 9038ecdb-e9f8-4e1a-98a9-87483b533b4f" \
  -H "Content-Type: application/json" \
  -d '{
  "requestedScopes": "[\n  \"invoice:read\"\n]",
  "label": "Server key"
}'

Example Response

{
  "key": {
    "keyId": "key_def456",
    "environment": "live",
    "requestedScopes": [
      "invoice:read"
    ],
    "activeScopes": [],
    "status": "pending"
  },
  "rawKey": "plat_live_a1b2c3d4...",
  "message": "Save this key securely - it cannot be retrieved again"
}
Go to top

Get Platform API Key (Platform)GET

/v1/platform/me/keys/{keyId}

Get details for a specific key with computed status and scopes. Requires platform API key with platform.key:manage scope.

curl -X GET https://oncade.gg/api/v1/platform/me/keys/key_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "key": {
    "keyId": "key_abc123",
    "environment": "live",
    "activeScopes": [
      "invoice:read"
    ],
    "status": "active"
  }
}
Go to top

Revoke Platform API Key (Platform)DELETE

/v1/platform/me/keys/{keyId}

Revoke a specific key. This cannot be undone. Requires platform API key with platform.key:manage scope.

curl -X DELETE https://oncade.gg/api/v1/platform/me/keys/key_abc123 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "message": "Key revoked successfully",
  "keyId": "key_abc123"
}
Go to top

Rotate Platform API Key (Platform)POST

/v1/platform/me/keys/{keyId}/rotate

Start key rotation: creates a new key with the same scopes and sets a grace period during which both keys are valid. The new raw key value is only returned once, at creation. Requires platform API key with platform.key:manage scope and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/me/keys/key_abc123/rotate \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 19fa64fd-81c7-47e7-b48d-5d4d53b373d4" \
  -H "Content-Type: application/json" \
  -d '{
  "gracePeriodDays": 7
}'

Example Response

{
  "newKey": {
    "keyId": "key_ghi789",
    "environment": "live",
    "activeScopes": [
      "invoice:read"
    ],
    "status": "active"
  },
  "rawKey": "plat_live_e5f6g7h8...",
  "oldKeyId": "key_abc123",
  "gracePeriodDays": 7,
  "message": "Save this key securely - it cannot be retrieved again. The old key will remain valid during the grace period."
}
Go to top

List Split Templates (Platform)GET

/v1/platform/split-templates

List non-archived split templates created by this platform for the target business. Requires platform API key with splitTemplate:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/split-templates \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "templates": [
    {
      "_id": "64f10b1cec13f995e9000081",
      "name": "Standard split",
      "mode": "percentage",
      "recipients": [
        {
          "email": "a@example.com",
          "name": "A",
          "percentage": 50
        },
        {
          "email": "b@example.com",
          "name": "B",
          "percentage": 50
        }
      ],
      "isArchived": false
    }
  ],
  "total": 1
}
Go to top

Create Split Template (Platform)POST

/v1/platform/split-templates

Create a new split template for the target business, marked as created by this platform. Requires platform API key with splitTemplate:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/split-templates \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: ede8a1d4-8faf-4b5f-b9b7-71c10e5ca65f" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Standard split",
  "mode": "percentage",
  "recipients": "[\n  {\n    \"email\": \"a@example.com\",\n    \"name\": \"A\",\n    \"percentage\": 50\n  },\n  {\n    \"email\": \"b@example.com\",\n    \"name\": \"B\",\n    \"percentage\": 50\n  }\n]"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000081",
  "name": "Standard split",
  "mode": "percentage",
  "isArchived": false
}
Go to top

Get Split Template (Platform)GET

/v1/platform/split-templates/{templateId}

Get details of a split template created by this platform. Requires platform API key with splitTemplate:read scope.

curl -X GET https://oncade.gg/api/v1/platform/split-templates/64f10b1cec13f995e9000081 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "_id": "64f10b1cec13f995e9000081",
  "name": "Standard split",
  "mode": "percentage",
  "isArchived": false
}
Go to top

Update Split Template (Platform)PATCH

/v1/platform/split-templates/{templateId}

Update a split template created by this platform. Requires platform API key with splitTemplate:update scope and Idempotency-Key header.

curl -X PATCH https://oncade.gg/api/v1/platform/split-templates/64f10b1cec13f995e9000081 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -d '{
  "name": "Updated split"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000081",
  "name": "Updated split",
  "mode": "percentage"
}
Go to top

Archive Split Template (Platform)DELETE

/v1/platform/split-templates/{templateId}

Archive (soft-delete) a split template created by this platform. Returns 204 No Content. Requires platform API key with splitTemplate:delete scope.

curl -X DELETE https://oncade.gg/api/v1/platform/split-templates/64f10b1cec13f995e9000081 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

null
Go to top

Record Gameplay Event (Platform)POST

/v1/platform/gameplay/events

Record a gameplay event (e.g. gameplay minutes, achievements) for a platform user. Uses idempotency key to prevent duplicate recording. Requires platform API key with gameplay:event:create scope.

curl -X POST https://oncade.gg/api/v1/platform/gameplay/events \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 85dedaf9-493c-42cd-b561-6a973d6a1866" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
  "gameId": "game_001",
  "eventName": "gameplay_minutes",
  "description": "30 minutes of gameplay"
}'

Example Response

{
  "eventId": "platform-plat_001-idem_key_123",
  "recorded": true
}
Go to top

Create Item (Platform)POST

/v1/platform/items

Create a new game item in the catalog. The item is created with isVisible=false (platform items are never shown on the public storefront). Supports USD pricing, virtual currency pricing, or both. Requires platform API key with item:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://oncade.gg/api/v1/platform/items \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: a3da1dce-4189-403d-9fb4-d23d771d4c40" \
  -H "Content-Type: application/json" \
  -d '{
  "gameId": "game_001",
  "name": "Gold Sword",
  "type": "consumable",
  "fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
  "description": "A powerful golden sword",
  "hasUsdPrice": "false",
  "virtualCurrencyPrices": "[\n  [\n    \"507f1f77bcf86cd799439022\",\n    500\n  ]\n]",
  "grantVirtualCurrencyId": "507f1f77bcf86cd799439022",
  "grantAmount": 100,
  "metadata": {
    "rarity": "legendary"
  },
  "forSale": "true"
}'

Example Response

{
  "_id": "507f1f77bcf86cd799439011",
  "gameId": "game_001",
  "name": "Gold Sword",
  "type": "consumable",
  "description": "A powerful golden sword",
  "hasUsdPrice": false,
  "price": 0,
  "virtualCurrencyPrices": [
    [
      "507f1f77bcf86cd799439022",
      500
    ]
  ],
  "fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
  "forSale": true,
  "isVisible": false,
  "perUserLimit": 0,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}
Go to top

List Items (Platform)GET

/v1/platform/items

List all items for a game with pagination. Returns items sorted by creation date (newest first). Requires platform API key with item:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/items?gameId=game_001&page=1&limit=50 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "gameId": "game_001",
      "name": "Gold Sword",
      "type": "consumable",
      "hasUsdPrice": false,
      "price": 0,
      "virtualCurrencyPrices": [
        [
          "507f1f77bcf86cd799439022",
          500
        ]
      ],
      "fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
      "forSale": true,
      "isVisible": false,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
Go to top

Get Item (Platform)GET

/v1/platform/items/{itemId}

Retrieve a single item by ID. The item must belong to a game owned by the target business. Requires platform API key with item:read scope and X-Target-Business-Id header.

curl -X GET https://oncade.gg/api/v1/platform/items/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "_id": "507f1f77bcf86cd799439011",
  "gameId": "game_001",
  "name": "Gold Sword",
  "type": "consumable",
  "description": "A powerful golden sword",
  "hasUsdPrice": false,
  "price": 0,
  "virtualCurrencyPrices": [
    [
      "507f1f77bcf86cd799439022",
      500
    ]
  ],
  "fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
  "forSale": true,
  "isVisible": false,
  "perUserLimit": 0,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}
Go to top

Update Item (Platform)PATCH

/v1/platform/items/{itemId}

Update an existing item. Only provided fields are modified — omitted fields remain unchanged. The item must belong to a game owned by the target business. Requires platform API key with item:update scope and X-Target-Business-Id header.

curl -X PATCH https://oncade.gg/api/v1/platform/items/ \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -d '{
  "name": "Diamond Sword",
  "virtualCurrencyPrices": "[\n  [\n    \"507f1f77bcf86cd799439022\",\n    750\n  ]\n]",
  "forSale": "true"
}'

Example Response

{
  "_id": "507f1f77bcf86cd799439011",
  "gameId": "game_001",
  "name": "Diamond Sword",
  "type": "consumable",
  "description": "A powerful golden sword",
  "hasUsdPrice": false,
  "price": 0,
  "virtualCurrencyPrices": [
    [
      "507f1f77bcf86cd799439022",
      750
    ]
  ],
  "fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
  "forSale": true,
  "isVisible": false,
  "perUserLimit": 0,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z"
}
Go to top

Archive Item (Platform)DELETE

/v1/platform/items/{itemId}

Archive an item by setting forSale=false and isVisible=false. The item is not permanently deleted. Requires platform API key with item:archive scope and X-Target-Business-Id header.

curl -X DELETE https://oncade.gg/api/v1/platform/items/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

null
Go to top

List Gameplay Rollups (Platform)GET

/v1/platform/gameplay/rollup

List gameplay rollups for the platform, optionally filtered by status. If a period query param is provided, returns the single rollup for that period instead of a list. Requires platform API key with gameplay:rollup:read scope.

curl -X GET https://oncade.gg/api/v1/platform/gameplay/rollup?status=draft \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "rollups": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "platformId": "plat_001",
      "businessId": "507f1f77bcf86cd799439022",
      "period": "2026-05",
      "status": "draft",
      "totalMinutes": 1200,
      "games": [
        {
          "gameId": "game_001",
          "gameName": "Space Blasters",
          "minutes": 720,
          "share": 0.6,
          "skuId": null,
          "skuDisplayName": null
        },
        {
          "gameId": "game_002",
          "gameName": "Puzzle Quest",
          "minutes": 480,
          "share": 0.4,
          "skuId": null,
          "skuDisplayName": null
        }
      ],
      "createdAt": "2026-06-01T00:00:00.000Z",
      "updatedAt": "2026-06-01T00:00:00.000Z"
    }
  ],
  "total": 1
}
Go to top

Generate Gameplay Rollup (Platform)POST

/v1/platform/gameplay/rollup

Generate a gameplay rollup for a given period. Aggregates all gameplay_minutes events for the platform during that month into a per-game breakdown. If a draft rollup already exists for the period it is overwritten; if a confirmed rollup exists the request is rejected. Requires platform API key with gameplay:rollup:generate scope.

curl -X POST https://oncade.gg/api/v1/platform/gameplay/rollup \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: e4e7df55-b7cc-4767-93b9-203dd8dd0d73" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-05"
}'

Example Response

{
  "rollup": {
    "_id": "507f1f77bcf86cd799439011",
    "platformId": "plat_001",
    "businessId": "507f1f77bcf86cd799439022",
    "period": "2026-05",
    "status": "draft",
    "totalMinutes": 1200,
    "games": [
      {
        "gameId": "game_001",
        "gameName": "Space Blasters",
        "minutes": 720,
        "share": 0.6,
        "skuId": null,
        "skuDisplayName": null
      },
      {
        "gameId": "game_002",
        "gameName": "Puzzle Quest",
        "minutes": 480,
        "share": 0.4,
        "skuId": null,
        "skuDisplayName": null
      }
    ],
    "createdAt": "2026-06-01T00:00:00.000Z",
    "updatedAt": "2026-06-01T00:00:00.000Z"
  }
}
Go to top

Confirm Gameplay Rollup (Platform)POST

/v1/platform/gameplay/rollup/confirm

Confirm a draft gameplay rollup for a given period. Once confirmed, the rollup cannot be regenerated. This endpoint only changes the rollup status — to create a distribution from the confirmed rollup, use the Pay dashboard. Requires platform API key with gameplay:rollup:confirm scope.

curl -X POST https://oncade.gg/api/v1/platform/gameplay/rollup/confirm \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: eece7e6a-ba92-44c3-a149-62d44bd7363a" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-05"
}'

Example Response

{
  "rollup": {
    "_id": "507f1f77bcf86cd799439011",
    "platformId": "plat_001",
    "businessId": "507f1f77bcf86cd799439022",
    "period": "2026-05",
    "status": "confirmed",
    "totalMinutes": 1200,
    "games": [
      {
        "gameId": "game_001",
        "gameName": "Space Blasters",
        "minutes": 720,
        "share": 0.6,
        "skuId": "sku_001",
        "skuDisplayName": "Space Blasters"
      },
      {
        "gameId": "game_002",
        "gameName": "Puzzle Quest",
        "minutes": 480,
        "share": 0.4,
        "skuId": "sku_002",
        "skuDisplayName": "Puzzle Quest"
      }
    ],
    "confirmedAt": "2026-06-02T12:00:00.000Z",
    "confirmedBy": "key_abc123",
    "createdAt": "2026-06-01T00:00:00.000Z",
    "updatedAt": "2026-06-02T12:00:00.000Z"
  }
}
Go to top