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://www.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,
  "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://www.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: 7ab93bcb-5d9c-4a98-8b09-5f96881ca416" \
  -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://www.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

Get User BalanceGET

/v1/vc/balances

Fetch a player balance for the specified currency.

curl -X GET https://www.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://www.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://www.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: 4130b935-e2ff-4153-a18b-9d5eb9ae7234" \
  -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://www.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: 3c08a6bd-8c5e-4af7-86fa-6ab2822cb7b9" \
  -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://www.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: 1e038e96-d505-4a48-8955-67e261f25ce0" \
  -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://www.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: 58b4c67b-74c2-4ab9-bacf-8d2b229b0dc8" \
  -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://www.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://www.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: cd5112d9-5ed6-4351-bbb1-32be1320a833"

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://www.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: 21fdf52f-d25e-4dde-adc2-ac9bb5ac9a88" \
  -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://www.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://www.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: 10d70044-6d06-497b-91a5-c9eb3fbde227"

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://www.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: f5373ed3-0474-4e18-b6ae-b8ee54b95693"

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://www.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: 2864dd53-4956-4d04-b0be-4c600a2a6a05" \
  -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://www.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://www.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: 4a317c2b-a1fb-4460-9bc8-cd966a2fe2c8"

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://www.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://www.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://www.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://www.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://www.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://www.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": "card",
  "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://www.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://www.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://www.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://www.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: 5ff6e665-8209-4439-984b-7fcb94f2cad2"

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://www.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://www.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://www.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: d59cc9ff-c67f-4773-9516-8e58a01aac66" \
  -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://www.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://www.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: ca48f77b-96d1-4e31-96a0-40036d99777f" \
  -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://www.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: 92fdc48f-1fac-4534-9030-0c7340f65c36" \
  -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://www.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: cc68a630-813b-4042-9131-5214eb46dd6b" \
  -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://www.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: 7a65b425-8d57-4ee0-9dee-074cc240d86c"

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://www.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: 8e159039-e4c1-4194-8fdd-940abf3389bf"
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://www.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: db1b79d6-5d85-4da3-a4b9-87e71c31baac" \
  -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://www.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://www.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: ade8b39d-9d94-49af-aa93-6115e5f396b1" \
  -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://www.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: 918516e1-1708-447c-adbc-769bb7b20308" \
  -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://www.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://www.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: ff4674f8-3e55-4d9f-b209-14a9821f1b4b" \
  -H "Content-Type: application/json" \
  -d '{
  "userRef": "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://www.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: b5ef2bb9-d275-49e3-a99e-a9ec7e66edb6"

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://www.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://www.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://www.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: 1f09b5e1-acab-48c4-8afb-ba21968476a7" \
  -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://www.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://www.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: b40ed701-8bf5-4884-b1b3-58773f6e5c69" \
  -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://www.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://www.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: d56b56b6-d90e-4e3a-8cd6-86a01ad36827" \
  -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 payment portal distribution page with this template pre-loaded.

curl -X GET https://www.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://pay.oncade.xyz/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://www.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: a1a71a45-25df-4c7e-9c8e-8bc3f81e09de" \
  -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://www.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://www.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: 42558130-2586-4313-88f1-c2c887fcac5b" \
  -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://www.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: 059294e3-818d-4ece-a679-99ea3074cf6d" \
  -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://www.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: e65081ae-26ac-43cd-8a24-1b41db928821" \
  -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://www.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: e138e1de-8ec8-4a1b-b486-affa004b34fe" \
  -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://www.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://www.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://www.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://www.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://www.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: 0caa52e0-6bc9-4605-b1a8-ded126f49ffd"

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://www.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: ca2dcb03-a363-47fb-b7f4-5636506be04d" \
  -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.xyz/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://www.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.xyz/dashboard/business/setup"
  },
  "links": {
    "home": "https://dev.oncade.xyz/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 collection account. Requires platform API key with business:update scope and X-Target-Business-Id header.

curl -X PATCH https://www.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://www.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.xyz/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://www.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 Receiving Accounts (Platform)GET

/v1/platform/receiving-accounts

List the target business's USD and EUR receiving accounts, newest first. Deactivated accounts are not returned. Returns 400 if currency is not USD or EUR. Requires platform API key with receiving_account:read scope and X-Target-Business-Id header.

curl -X GET https://www.oncade.gg/api/v1/platform/receiving-accounts?currency=USD \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "receivingAccounts": [
    {
      "_id": "64f10b1cec13f995e9000021",
      "accountId": "64f10b1cec13f995e9000021",
      "currency": "USD",
      "status": "active",
      "label": "USD Receiving Account",
      "createdAt": "2026-10-01T00:00:00.000Z",
      "updatedAt": "2026-10-01T00:00:00.000Z"
    }
  ]
}
Go to top

Create Receiving Account (Platform)POST

/v1/platform/receiving-accounts

Create a USD or EUR receiving account for the target business and return it with status 201. A business can hold one active account per currency: a second returns 409 DUPLICATE_CURRENCY_ACCOUNT. Returns 400 for an invalid currency or label. Requires platform API key with receiving_account:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.oncade.gg/api/v1/platform/receiving-accounts \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: d3a4773c-d2d1-464a-84ec-22814befd1c2" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "EUR",
  "label": "EU customer payments"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000022",
  "accountId": "64f10b1cec13f995e9000022",
  "currency": "EUR",
  "status": "pending",
  "label": "EU customer payments",
  "createdAt": "2026-10-01T00:00:00.000Z",
  "updatedAt": "2026-10-01T00:00:00.000Z"
}
Go to top

Get Receiving Account Deposit Instructions (Platform)GET

/v1/platform/receiving-accounts/{accountId}/deposit-instructions

Get the bank details a payer uses to send money to one of the target business's receiving accounts. EUR accounts return iban and bic on the SEPA rail; USD accounts return accountNumber and routingNumber, and rails lists only the rails those numbers accept: ["ach", "wire"] when the same numbers take both, otherwise ["ach"] or ["wire"]. Send a wire only when rails includes "wire". The instructions field carries the full rail-specific details. Returns 404 NOT_FOUND if the account does not exist for this business, 422 INSTRUCTIONS_UNAVAILABLE if the account has no deposit instructions yet, and 502 INSTRUCTIONS_FETCH_FAILED if the bank details cannot be loaded right now. Requires platform API key with receiving_account:read scope and X-Target-Business-Id header.

curl -X GET https://www.oncade.gg/api/v1/platform/receiving-accounts/64f10b1cec13f995e9000022/deposit-instructions \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "currency": "EUR",
  "rails": [
    "sepa"
  ],
  "beneficiaryName": "Acme Games",
  "bankName": "Example Bank",
  "bankAddress": "1 Example Street, Dublin, Ireland",
  "iban": "IE00EXMP00000000000000",
  "bic": "EXMPIE2D",
  "depositMessage": "REF123456",
  "instructions": {
    "rail": "sepa",
    "amount": "",
    "currency": "eur",
    "depositMessage": "REF123456",
    "bankName": "Example Bank",
    "bankAddress": "1 Example Street, Dublin, Ireland",
    "accountHolderName": "Acme Games",
    "iban": "IE00EXMP00000000000000",
    "bic": "EXMPIE2D"
  }
}
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://www.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://www.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: ce15b93d-9f1f-4e4e-8f24-9406eb2a4b5f" \
  -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 and X-Target-Business-Id header.

curl -X GET https://www.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, X-Target-Business-Id header, and Idempotency-Key header.

curl -X PATCH https://www.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 and X-Target-Business-Id header. Returns 204 No Content.

curl -X DELETE https://www.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 and X-Target-Business-Id header.

curl -X PUT https://www.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: d8539874-04b1-4d17-80be-2b6a9e84031b"

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 and X-Target-Business-Id header.

curl -X PUT https://www.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: ae3e28c6-ccce-46b7-80fc-62f6567e1e05"

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 and X-Target-Business-Id header.

curl -X POST https://www.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: 1f87496a-2f8a-45ec-9eb0-29554e6f8126" \
  -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 and X-Target-Business-Id header.

curl -X GET https://www.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 and X-Target-Business-Id header.

curl -X GET https://www.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 and X-Target-Business-Id header.

curl -X GET https://www.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, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.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: aff65f66-f54f-4bba-ae16-c81eb2e52258"

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. `expired` is not always final: a session can move from `expired` to `completed` within one hour after `expiresAt`, when a payment confirmed on-chain before `expiresAt` is recorded late. Requires platform API key with campaign:funds:read scope and X-Target-Business-Id header.

curl -X GET https://www.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 and X-Target-Business-Id header.

curl -X DELETE https://www.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://www.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. The response field environment ("test" or "live") is the mode of your API key; the business owner can pay a "dashboard" distribution only while their dashboard is in that mode. Requires platform API key with distribution:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.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: d6b355f4-6705-4099-a65f-2bd470051908" \
  -H "Content-Type: application/json" \
  -d '{
  "recipients": "[\n  {\n    \"email\": \"player@example.com\",\n    \"percentage\": 100\n  }\n]",
  "totalAmountCents": 10000,
  "payoutPath": "partner"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000011",
  "businessId": "64f10b1cec13f995e9000001",
  "totalAmountCents": 10000,
  "status": "pending",
  "payoutPath": "partner",
  "environment": "live",
  "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://www.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. Once the payer starts paying, expiresAt moves out by up to 24 hours so the payment can be recorded. The distribution must have been created with payoutPath "fund_session"; otherwise returns 409 PAYOUT_PATH_MISMATCH. Requires platform API key with distribution:funds:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.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: d7099877-2f54-4f1a-93de-6b261e3c3c93"

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. Once the payer starts paying, expiresAt moves out by up to 24 hours so the payment can be recorded. Requires platform API key with distribution:funds:read scope and X-Target-Business-Id header.

curl -X GET https://www.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 and X-Target-Business-Id header.

curl -X DELETE https://www.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

Mark Direct Transfers Sent (Platform)POST

/v1/platform/distributions/{distributionId}/direct-transfers/mark-sent

Record the transaction your platform used to pay the direct-transfer recipients and fees of a distribution with payoutPath "partner". Oncade checks the transaction on the network of your API key: it must have succeeded, been mined after the distribution was created, and its USDC transfers must pay every unsent direct recipient and fee wallet at least the stored amount. Then it marks those items sent and emails the recipients. Send all direct transfers and fees in one transaction. Calling again with the same hash after they are recorded returns 200 with the distribution and sends no emails. Errors: 400 for a malformed transactionHash; 400 INVALID_STATUS when the distribution is not pending, funded or processing; 404 if the distribution is not found for this business and platform; 409 PAYOUT_PATH_MISMATCH for another payout path, including a partner distribution the business owner has started paying from their dashboard; 409 PAYOUT_ALREADY_STARTED while the business is paying it; 409 NOTHING_TO_RECORD when there is nothing unsent; 409 TRANSACTION_ALREADY_USED when the hash is recorded on another distribution; 409 RECORDING_IN_PROGRESS while another request records the same hash (retry shortly); 422 TRANSACTION_NOT_VERIFIED when the on-chain check fails or a recipient has no wallet on file. Requires platform API key with distribution:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.oncade.gg/api/v1/platform/distributions/64f10b1cec13f995e9000011/direct-transfers/mark-sent \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: 6c4243bc-1c3e-4fae-9b3e-283e8306bbee" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x4c9a3e1f0b7d2a6c8e5f1d3b9a7c2e4f6d8b0a1c3e5f7d9b2a4c6e8f0d1b3a5c"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000011",
  "businessId": "64f10b1cec13f995e9000001",
  "totalAmountCents": 188,
  "status": "completed",
  "payoutPath": "partner",
  "currency": "USD"
}
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. Returns 201 even when some recipients fail. Each entry in result.errors is { email, error, code? }: error is fixed display text chosen by code, and code is INVALID_INPUT (the recipient's gift details are invalid), DUPLICATE_GIFT (a gift with the same vault address, root hash, or claim code already exists), or absent for an unexpected failure. The text does not name the failing field. Branch on code, not on the error text. Returns 409 PAYOUT_PATH_MISMATCH, and keeps none of the records, once the business owner has started paying the distribution from their dashboard.

curl -X POST https://www.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: 0ce7bf15-0290-4591-b119-ee9c6a3ac607" \
  -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]",
  "distributionId": "64f10b1cec13f995e9000011"
}'

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": 1,
    "errors": [
      {
        "email": "second@example.com",
        "error": "Some of these gifts were already created",
        "code": "DUPLICATE_GIFT"
      }
    ]
  }
}
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. The distribution must belong to the target business and have payoutPath "partner" (the default); otherwise returns 404 or 409 PAYOUT_PATH_MISMATCH. A partner distribution the business owner has started paying from their dashboard has payoutPath "dashboard" and also returns 409 PAYOUT_PATH_MISMATCH. Requires platform API key with gift:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.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: 98b709db-3c0f-49ff-81e0-4938994a1120" \
  -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://www.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://www.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: d6138427-dc0b-42e3-a26b-0832be8bcfc5"

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://www.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. Response field `inviteId` is deprecated: use `_id`. Will be removed in a future version.

curl -X POST https://www.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: b8f47ec2-4736-4a98-aeaf-b77ee3f90e1c" \
  -H "Content-Type: application/json" \
  -d '{
  "businessId": "64f10b1cec13f995e9000001",
  "requestedScopes": "[\n  \"invoice:read\",\n  \"invoice:create\"\n]"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000041",
  "inviteId": "64f10b1cec13f995e9000041",
  "platformId": "plat_001",
  "businessId": "64f10b1cec13f995e9000001",
  "requestedScopes": [
    "invoice:read",
    "invoice:create"
  ],
  "status": "pending",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "expiresAt": "2026-01-08T00:00:00.000Z"
}
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://www.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: 5aee3d4f-4c3c-449e-808f-2e633435e4b1"

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://www.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). Returns 400 NO_PAYOUT_WALLET when payToTarget is BUSINESS and the business has no payout wallet, and 422 INVOICE_BELOW_MINIMUM when the amount is below the minimum for the current fee schedule. Requires platform API key with invoice:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.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: d1dfaa24-3bf8-4f0c-8535-dd7be1a79d69" \
  -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]",
  "externalMetadata": {
    "poNumber": "PO-1042"
  }
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000051",
  "invoiceNumber": "INV-0001",
  "status": "draft",
  "total": 100,
  "currency": "USD",
  "externalMetadata": {
    "poNumber": "PO-1042"
  },
  "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. Optional response fields: externalMetadata (the object you sent on create or update), paymentMethod (rail of the open or last bank pay-in: onchain, ach, wire, sepa, pix, spei, or faster_payments), paymentTxHash (on-chain hash that settled the invoice), manualPaymentReference (the reference, such as a check number, the business entered when it marked the invoice paid by hand; not verified, and not settable through the API), recurring ({ templateId, period, triggeredBy? } where triggeredBy is manual or scheduled; present on invoices generated from a recurring template), and depositInstructions (an array with one set of bank deposit details per rail the payer started; each set carries its own rail, one of ach, wire, sepa, pix, spei, or faster_payments, and the fields that rail needs; matchBy is reference or exact_amount when present). Requires platform API key with invoice:read scope and X-Target-Business-Id header.

curl -X GET https://www.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": "processing",
  "total": 100,
  "currency": "USD",
  "externalMetadata": {
    "poNumber": "PO-1042"
  },
  "paymentMethod": "ach",
  "paymentTxHash": "0x9f2c5a1e7b3d4c6f8a0e1d2b3c4a5f60718293a4b5c6d7e8f9012a3b4c5d6e7f",
  "manualPaymentReference": "CHK-1042",
  "recurring": {
    "templateId": "64f10b1cec13f995e9000071",
    "period": "2026-07",
    "triggeredBy": "scheduled"
  },
  "depositInstructions": [
    {
      "rail": "ach",
      "amount": "100.00",
      "currency": "usd",
      "depositMessage": "INV-0001",
      "matchBy": "reference",
      "bankName": "Example Bank",
      "bankAddress": "1 Example Way, Springfield",
      "accountHolderName": "Acme Inc",
      "beneficiaryAddress": "2 Acme Plaza, Springfield",
      "bankAccountNumber": "111222333",
      "bankRoutingNumber": "444555666",
      "imad": "20260718MMQFMP0000001"
    },
    {
      "rail": "sepa",
      "amount": "92.00",
      "currency": "eur",
      "depositMessage": "INV-0001",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX"
    },
    {
      "rail": "pix",
      "amount": "500.00",
      "currency": "brl",
      "depositMessage": "INV-0001",
      "pixKey": "pix@example.com"
    },
    {
      "rail": "spei",
      "amount": "1800.00",
      "currency": "mxn",
      "depositMessage": "INV-0001",
      "clabe": "646180157000000004",
      "trackingNumber": "TRK123"
    }
  ]
}
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. Returns 409 INVOICE_STATUS_CHANGED when the invoice status changed while the request was processing. Returns 422 INVOICE_INVALID_STATUS when the status change is not a valid transition, 422 INVOICE_BELOW_MINIMUM when the amount is below the minimum for the current fee schedule, and 400 NO_PAYOUT_WALLET when payToTarget is BUSINESS and the business has no payout wallet. Requires platform API key with invoice:update scope and X-Target-Business-Id header.

curl -X PUT https://www.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: 30fb0b69-f932-431f-b0d9-c7a1efed204b" \
  -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",
  "externalMetadata": {
    "poNumber": "PO-1042"
  }
}'

Example Response

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

Cancel Invoice (Platform)POST

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

Cancel a draft or sent invoice. Returns 409 INVOICE_STATUS_CHANGED when the invoice status changed while the request was processing, and 409 INVOICE_MODIFIED when expectedUpdatedAt is sent and the invoice was edited after it. Returns 422 INVOICE_INVALID_STATUS when the invoice is in a status that cannot be cancelled. Requires platform API key with invoice:cancel scope and X-Target-Business-Id header.

curl -X POST https://www.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: d60d9b07-5d14-4701-920c-4bd87dfbc033" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedUpdatedAt": "2026-07-18T15:04:05.000Z"
}'

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. Returns 409 INVOICE_STATUS_CHANGED when the invoice status changed while the request was processing, and 409 INVOICE_MODIFIED when expectedUpdatedAt is sent and the invoice was edited after it. Returns 422 INVOICE_INVALID_STATUS when the invoice is in a status that cannot be sent. Requires platform API key with invoice:send scope and X-Target-Business-Id header.

curl -X POST https://www.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: 623715a9-6503-4c6e-be98-a3c832e0469c" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedUpdatedAt": "2026-07-18T15:04:05.000Z"
}'

Example Response

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

Export Invoices CSV (Platform)GET

/v1/platform/invoices/export

Download a CSV export of the target business's invoices (sent/AR or received/AP view). Requires platform API key with invoice:read scope and X-Target-Business-Id header. Gated behind the ENABLE_BUSINESS_REPORTS feature flag.

curl -X GET https://www.oncade.gg/api/v1/platform/invoices/export?view=outgoing&dateRange=30d \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1"

Example Response

"text/csv file download"
Go to top

List Recurring Invoices (Platform)GET

/v1/platform/invoice-templates

List recurring invoice templates for the target business, newest first. Each template generates a draft invoice on its anchor day every month; the draft is never sent automatically. Requires platform API key with invoice:read scope and X-Target-Business-Id header.

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

Example Response

{
  "templates": [
    {
      "_id": "64f10b1cec13f995e9000071",
      "businessId": "64f10b1cec13f995e9000072",
      "name": "Monthly retainer",
      "status": "active",
      "receiverName": "Acme",
      "receiverEmail": "billing@acme.com",
      "items": [
        {
          "_id": "64f10b1cec13f995e9000073",
          "description": "Retainer",
          "quantity": 1,
          "rate": 500,
          "amount": 500
        }
      ],
      "tax": 0,
      "currency": "USD",
      "payToTarget": "BUSINESS",
      "recurrence": {
        "anchorDay": 15
      },
      "netDays": 30,
      "nextRunAt": "2026-11-15T00:00:00.000Z",
      "environment": "live",
      "createdAt": "2026-10-11T00:00:00.000Z",
      "updatedAt": "2026-10-11T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Go to top

Create Recurring Invoice (Platform)POST

/v1/platform/invoice-templates

Create a recurring invoice template for the target business. On the anchor day each month a draft invoice is generated from it for the business to review and send; generated invoices stay drafts and are not sent automatically. Returns 201 with a Location header. Requires platform API key with invoice:create scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X POST https://www.oncade.gg/api/v1/platform/invoice-templates \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: c62ff09a-185c-496f-93d2-e77ec3ea225c" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Monthly retainer",
  "recurrence": {
    "anchorDay": 15
  },
  "items": "[\n  {\n    \"description\": \"Retainer\",\n    \"quantity\": 1,\n    \"rate\": 500\n  }\n]",
  "receiverName": "Acme",
  "receiverEmail": "billing@acme.com",
  "payToTarget": "BUSINESS"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000071",
  "businessId": "64f10b1cec13f995e9000072",
  "name": "Monthly retainer",
  "status": "active",
  "receiverName": "Acme",
  "receiverEmail": "billing@acme.com",
  "items": [
    {
      "_id": "64f10b1cec13f995e9000073",
      "description": "Retainer",
      "quantity": 1,
      "rate": 500,
      "amount": 500
    }
  ],
  "tax": 0,
  "currency": "USD",
  "payToTarget": "BUSINESS",
  "recurrence": {
    "anchorDay": 15
  },
  "netDays": 30,
  "nextRunAt": "2026-11-15T00:00:00.000Z",
  "environment": "live",
  "createdAt": "2026-10-11T00:00:00.000Z",
  "updatedAt": "2026-10-11T00:00:00.000Z"
}
Go to top

Get Recurring Invoice (Platform)GET

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

Get a recurring invoice template by ID. Returns 403 if the template belongs to a different business than X-Target-Business-Id. Requires platform API key with invoice:read scope and X-Target-Business-Id header.

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

Example Response

{
  "_id": "64f10b1cec13f995e9000071",
  "businessId": "64f10b1cec13f995e9000072",
  "name": "Monthly retainer",
  "status": "active",
  "receiverName": "Acme",
  "receiverEmail": "billing@acme.com",
  "items": [
    {
      "_id": "64f10b1cec13f995e9000073",
      "description": "Retainer",
      "quantity": 1,
      "rate": 500,
      "amount": 500
    }
  ],
  "tax": 0,
  "currency": "USD",
  "payToTarget": "BUSINESS",
  "recurrence": {
    "anchorDay": 15
  },
  "netDays": 30,
  "nextRunAt": "2026-11-15T00:00:00.000Z",
  "environment": "live",
  "createdAt": "2026-10-11T00:00:00.000Z",
  "updatedAt": "2026-10-11T00:00:00.000Z"
}
Go to top

Update Recurring Invoice (Platform)PUT

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

Update a recurring invoice template. The body carries the same fields as create; name, recurrence, items and a recipient are always required. Changing the anchor day reschedules the next run; other edits keep the schedule. Invoices already generated are not changed. Requires platform API key with invoice:update scope and X-Target-Business-Id header.

curl -X PUT https://www.oncade.gg/api/v1/platform/invoice-templates/64f10b1cec13f995e9000071 \
  -H "Authorization: Bearer SERVER_API_KEY" \
  -H "X-Game-Id: GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Idempotency-Key: d383b65d-b7b9-4ddb-a3c8-e81925d83831" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Monthly retainer",
  "recurrence": {
    "anchorDay": 15
  },
  "items": "[\n  {\n    \"description\": \"Retainer\",\n    \"quantity\": 1,\n    \"rate\": 500\n  }\n]",
  "receiverName": "Acme",
  "receiverEmail": "billing@acme.com",
  "payToTarget": "BUSINESS"
}'

Example Response

{
  "_id": "64f10b1cec13f995e9000071",
  "businessId": "64f10b1cec13f995e9000072",
  "name": "Monthly retainer",
  "status": "active",
  "receiverName": "Acme",
  "receiverEmail": "billing@acme.com",
  "items": [
    {
      "_id": "64f10b1cec13f995e9000073",
      "description": "Retainer",
      "quantity": 1,
      "rate": 500,
      "amount": 500
    }
  ],
  "tax": 0,
  "currency": "USD",
  "payToTarget": "BUSINESS",
  "recurrence": {
    "anchorDay": 15
  },
  "netDays": 30,
  "nextRunAt": "2026-11-15T00:00:00.000Z",
  "environment": "live",
  "createdAt": "2026-10-11T00:00:00.000Z",
  "updatedAt": "2026-10-11T00:00:00.000Z"
}
Go to top

Delete Recurring Invoice (Platform)DELETE

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

Delete a recurring invoice template so no further drafts are generated. Invoices already generated are kept. To stop temporarily, update the template with status "paused" instead. Returns 204. Requires platform API key with invoice:cancel scope and X-Target-Business-Id header.

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

Example Response

"No content (204)"
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://www.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: dbf166a5-67fc-4e09-a80a-edf12594fe5e" \
  -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://www.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://www.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: 25405796-c7d4-43c7-889d-3d4f8d885098" \
  -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://www.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://www.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: 36948f9d-46e2-4383-afca-75ccf5103fb4" \
  -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://www.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://www.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://www.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: 9361cdbd-68f5-43a5-8462-1b3a9cfdf382" \
  -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://www.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://www.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: 0f8a23ca-8dd8-476a-a286-841029cfa29b" \
  -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 for the target business. Requires platform API key with splitTemplate:read scope and X-Target-Business-Id header.

curl -X GET https://www.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 for the target business. Requires platform API key with splitTemplate:update scope, X-Target-Business-Id header, and Idempotency-Key header.

curl -X PATCH https://www.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 for the target business. Returns 204 No Content. Requires platform API key with splitTemplate:delete scope and X-Target-Business-Id header.

curl -X DELETE https://www.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://www.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: ef230894-cc76-4b3b-b66a-6c1198b18fc4" \
  -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://www.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: 2e1c1cfa-9433-486c-bf2c-f5301c65e508" \
  -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://www.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://www.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://www.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://www.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://www.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://www.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: fe64e08d-1662-403f-bcf6-93b8b12d3644" \
  -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://www.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: 1e095573-25bb-4941-aa95-65c85b7e0391" \
  -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