API Reference
The Oncade Server API lets you manage account linking, products, wallets and purchases from your game servers. All requests require HTTPS and include authentication headers.
NOTE: we also provide the Oncade API Test Dashboard. You can try out requests live at Oncade API Test Dashboard.
Common headers
Every request must include the Authorization header with Bearer <your_api_key> and X-Oncade-API-Version (defaults to v1). Game endpoints require X-Game-Id with a server API key. Campaign endpoints (/v1/campaign/...) require X-Campaign-Id with a campaign API key. For POST and PUT requests, supply an Idempotency-Key to safely retry requests without creating duplicates.
Get GameGET
/v1/game
Fetch game details for the game associated with the API key.
curl -X GET https://oncade.gg/api/v1/game \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"gameId": "test-game",
"name": "Test Game",
"description": "An awesome test game",
"imageUrl": "https://example.com/image.png",
"smallImageUrl": "https://example.com/small.png",
"storeImageUrl": "https://example.com/store.png",
"demoUrl": "https://example.com/demo",
"steamAppId": "12345",
"discordUrl": "https://discord.gg/test",
"screenshots": [
"https://example.com/ss1.png",
"https://example.com/ss2.png"
],
"status": "approved",
"environment": "test",
"affiliateRate": 10,
"enableTip": true,
"isVisible": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}Initiate Account LinkPOST
/v1/users/link/initiate
Begin linking a player account. Email is optional — the player can sign in or sign up during the flow. Returns 201 with a confirmation URL for new sessions (200 if one already exists). Dispatches User.Account.Link.Started.
curl -X POST https://oncade.gg/api/v1/users/link/initiate \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 62371231-ce5a-4761-b085-42e125080dd2" \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com"
}'Example Response
{
"url": "https://oncade.gg/link?session=session_abc123",
"sessionKey": "session_abc123"
}Initiate Account Link (GET)GET
/v1/users/link/initiate
Begin linking a player account without an email. Equivalent to POST /v1/users/link/initiate with no email body. Returns 201 with a confirmation URL.
curl -X GET https://oncade.gg/api/v1/users/link/initiate \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"url": "https://oncade.gg/link?session=session_abc123",
"sessionKey": "session_abc123"
}Create Virtual CurrencyPOST
/v1/vc/currencies
Define a virtual currency for your game. Requires an Idempotency-Key header.
curl -X POST https://oncade.gg/api/v1/vc/currencies \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: ce35f8bc-dc4f-4d3e-a7c4-65c43f8ee94a" \
-H "Content-Type: application/json" \
-d '{
"code": "GEM",
"name": "Gems",
"baseUnitsPerVcUnit": "100",
"centralWalletAddress": "wallet-placeholder"
}'Example Response
{
"currency": {
"_id": "cur_123",
"code": "GEM",
"name": "Gems",
"status": "active",
"baseUnitsPerVcUnit": "100",
"centralWalletAddress": "wallet-placeholder"
}
}List Virtual CurrenciesGET
/v1/vc/currencies
Return paginated virtual currencies for the authenticated game.
curl -X GET https://oncade.gg/api/v1/vc/currencies?page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "cur_123",
"code": "GEM",
"name": "Gems",
"status": "active",
"baseUnitsPerVcUnit": "100",
"centralWalletAddress": "wallet-placeholder"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Update Virtual CurrencyPATCH
/v1/vc/currencies/{currencyId}
Update currency fields. All body params are optional.
curl -X PATCH https://oncade.gg/api/v1/vc/currencies/cur_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Get User BalanceGET
/v1/vc/balances
Fetch a player balance for the specified currency.
curl -X GET https://oncade.gg/api/v1/vc/balances?currencyId=cur_123&userRef=link_usr_abc \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"currencyId": "cur_123",
"userRef": "link_usr_abc",
"balanceUnits": "500",
"updatedAt": "2024-05-01T00:00:00.000Z"
}List Journal EntriesGET
/v1/vc/journals
Return paginated ledger entries for a player and currency. Results are sorted newest-first.
curl -X GET https://oncade.gg/api/v1/vc/journals?currencyId=cur_123&userRef=link_usr_abc \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "jrnl_001",
"type": "credit",
"postings": [
{
"account": {
"type": "pool",
"address": "wallet-placeholder"
},
"deltaUnits": "-500"
},
{
"account": {
"type": "user",
"userRef": "link_usr_abc"
},
"deltaUnits": "500"
}
],
"createdAt": "2024-05-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Credit Player BalancePOST
/v1/vc/credits
Move units from the treasury into a player balance. Returns 201 with a journal entry.
curl -X POST https://oncade.gg/api/v1/vc/credits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 8c09e17f-de6d-4bb3-930d-94f5436ce60e" \
-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"
}
]
}Debit Player BalancePOST
/v1/vc/debits
Remove units from a player balance and return them to the treasury. Returns 201 with a journal entry.
curl -X POST https://oncade.gg/api/v1/vc/debits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 132a71ef-6840-4885-b9ec-4f7578959d25" \
-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"
}
]
}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.
curl -X POST https://oncade.gg/api/v1/vc/batch \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 47353420-9600-4fdc-bb7f-de601332e168" \
-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"
}
]
}Create Cashout RequestPOST
/v1/vc/cashouts
Stage a cashout for manual review. Balance is not debited until approval. Returns 201.
curl -X POST https://oncade.gg/api/v1/vc/cashouts \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 9cb3bdb9-d0c9-4a36-8848-88b0a3425763" \
-H "Content-Type: application/json" \
-d '{
"currencyId": "cur_123",
"userRef": "link_usr_abc",
"units": "2000"
}'Example Response
{
"cashoutRequestId": "co_001"
}List Cashout RequestsGET
/v1/vc/cashouts
Return cashout requests with pagination. Filter by status or user.
curl -X GET https://oncade.gg/api/v1/vc/cashouts?currencyId=cur_123&status=pendingReview&page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "co_001",
"userRef": "link_usr_abc",
"unitsRequested": "2000",
"status": "pendingReview",
"requestedRate": {
"baseUnitsPerVcUnit": "100",
"capturedAt": "2024-05-01T00:00:00.000Z"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Approve Cashout RequestPOST
/v1/vc/cashouts/{cashoutRequestId}/approve
Approve and execute a cashout. Debits the requested units and records a conversion.
curl -X POST https://oncade.gg/api/v1/vc/cashouts/co_001/approve \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 2869155c-2f8e-4d73-81f5-b6d36bd5a581"Example Response
{
"transactionId": "jrnl_convert_1",
"usedBaseUnitsPerVcUnit": "100",
"convertedBaseUnits": "200000"
}Reject Cashout RequestPOST
/v1/vc/cashouts/{cashoutRequestId}/reject
Reject a pending cashout request. Returns 204.
curl -X POST https://oncade.gg/api/v1/vc/cashouts/co_001/reject \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 3fa58aee-8254-426b-b30a-26ecdf4f703e" \
-H "Content-Type: application/json" \
-d '{
"reason": "KYC pending"
}'Get CampaignGET
/v1/campaign/{campaignId}
Fetch campaign details, status, and balances.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"campaign": {
"id": "cmp_demo",
"name": "My Campaign",
"environment": "test",
"status": "started",
"businessId": "65fa1234abcdef5678901234",
"address": "0xabcDEFabcDEFabcDEFabcDEFabcDEFabcDEFabcd",
"createdAt": "2025-09-01T12:34:56.789Z",
"updatedAt": "2025-09-01T12:34:56.789Z",
"totalAmountFunded": 0,
"totalAmountPaidOut": 0,
"availableToWithdraw": 0
}
}Start CampaignPUT
/v1/campaign/{campaignId}/start
Activate the campaign. Returns 202 and enqueues a background job.
curl -X PUT https://oncade.gg/api/v1/campaign/cmp_demo/start \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: c1401003-4d5a-4bcd-a376-c2f8ee4699dd"Example Response
{
"success": true,
"message": "Start enqueued"
}Stop CampaignPUT
/v1/campaign/{campaignId}/stop
Stop the campaign. Returns 202 and enqueues a background job.
curl -X PUT https://oncade.gg/api/v1/campaign/cmp_demo/stop \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: d3a6d32b-12fd-4b02-a410-fea61eae53a7"Example Response
{
"success": true,
"message": "Stop enqueued"
}Enqueue Campaign EventPOST
/v1/campaign/{campaignId}/events
Record a campaign event for a linked user. Returns 202.
curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/events \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: a8cd8f2f-92a0-44ba-a18f-8c8f637e95b9" \
-H "Content-Type: application/json" \
-d '{
"eventCode": "quest_complete",
"userRef": "link_usr_123"
}'Example Response
{
"success": true,
"message": "Event enqueued"
}List Campaign EventsGET
/v1/campaign/{campaignId}/events
Return configured campaign events.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/events \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"events": [
{
"code": "quest_complete",
"name": "Quest Complete",
"payoutAmount": 1000
}
]
}Withdraw Campaign FundsPOST
/v1/campaign/{campaignId}/withdraw
Withdraw remaining funds from a stopped campaign. Returns 202.
curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/withdraw \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 369e2c61-400c-4a97-a864-5fb740d162cc"Example Response
{
"success": true,
"message": "Withdrawal enqueued"
}Get Campaign User DetailsGET
/v1/campaign/{campaignId}/user/{userId}
Fetch a user's status within a campaign.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/user/user_123 \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"data": {
"campaignId": "cmp_demo",
"userId": "user_123",
"status": "started",
"environment": "test"
}
}Get Campaign User EventsGET
/v1/campaign/{campaignId}/user/{userId}/events
Fetch paginated event history for a user in a campaign.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/user/user_123/events?limit=10&offset=0 \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"data": {
"campaignId": "cmp_demo",
"userId": "user_123",
"environment": "test",
"transactions": [
{
"id": "507f1f77bcf86cd799439011",
"campaignId": "cmp_demo",
"userRef": "user_123",
"eventCode": "quest_complete",
"eventName": "Quest Complete",
"payoutAmount": 1000,
"transactionHash": "0xabc123def456...",
"createdAt": "2025-10-01T14:30:00.000Z"
}
],
"pagination": {
"limit": 10,
"offset": 0,
"total": 1,
"hasMore": false
}
}
}Get Link StatusGET
/v1/users/link/details
Return metadata for an account link session. Includes the userRef once approved and the spendPermission when enabled.
curl -X GET https://oncade.gg/api/v1/users/link/details?session=session_abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"namespaceType": "game",
"gameId": "game_123",
"gameName": "Demo Game",
"prefilledEmail": "player@example.com",
"userRef": "user_123",
"spendPermission": {
"tenantId": "0xbadd768a99ec4b5c...",
"tenantName": "Demo Game",
"tokenAddress": "0x036CbD53842c...",
"allowanceUSDC": "250",
"depositUSDC": "10",
"periodSeconds": 604800,
"durationSeconds": 7776000,
"tenantModuleAddress": "0x4042Ff8Edc...",
"networkKey": "base-sepolia"
}
}Initiate Campaign Account LinkPOST
/v1/campaign/{campaignId}/users/link/initiate
Begin linking a player account scoped to a campaign. Returns 201 with a confirmation URL for new sessions (200 if one already exists). Dispatches User.Account.Link.Started.
curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/users/link/initiate \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 4f9458f5-fa31-43ad-a3c0-1c00e3ee31d3" \
-H "Content-Type: application/json" \
-d '{
"email": "player@example.com"
}'Example Response
{
"url": "https://oncade.gg/link?session=session_abc123",
"sessionKey": "session_abc123"
}Campaign Link StatusGET
/v1/campaign/{campaignId}/users/link/details
Fetch status of a campaign-scoped link session. Includes userRef when approved and spendPermission when enabled.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/users/link/details?session=session_abc123 \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"campaignId": "cmp_demo",
"campaignName": "Demo Campaign",
"prefilledEmail": "player@example.com",
"status": "approved",
"userRef": "user_123",
"spendPermission": {
"tenantId": "0xbadd768a99ec4b5c...",
"tenantName": "Demo Campaign",
"tokenAddress": "0x036CbD53842c...",
"allowanceUSDC": "250",
"depositUSDC": "10",
"periodSeconds": 604800,
"durationSeconds": 7776000,
"tenantModuleAddress": "0x4042Ff8Edc...",
"networkKey": "base-sepolia"
}
}Get User PurchasesGET
/v1/users/{userRef}/purchases
List purchase history for a user.
curl -X GET https://oncade.gg/api/v1/users/user_123/purchases?limit=10&offset=20&type=subscription \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
[
{
"itemId": "507f1f77bcf86cd799439011",
"gameId": "game_123",
"createdAt": "2024-03-10T14:12:01.123Z",
"item": {
"name": "Founders Pass",
"type": "subscription",
"price": 1299
}
}
]Get User InfoGET
/v1/users/{userRef}
Fetch profile information for a user.
curl -X GET https://oncade.gg/api/v1/users/user_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"userRef": "user_123",
"email": "player@example.com",
"profileImageUrl": "https://cdn.example.com/u/123.png",
"subscriptions": [
{
"itemId": "item_456",
"status": "Active",
"subscriptionId": "sub_123",
"planCode": "PREMIUM_MONTHLY",
"planId": "plan_abc"
}
]
}Get User SubscriptionsGET
/v1/users/{userRef}/subscriptions
Fetch all subscriptions for a user.
curl -X GET https://oncade.gg/api/v1/users/user_123/subscriptions \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"subscriptions": [
{
"itemId": "item_456",
"status": "Active",
"subscriptionId": "sub_123",
"planCode": "PREMIUM_MONTHLY",
"planId": "plan_abc"
},
{
"itemId": "item_789",
"status": "Canceled",
"subscriptionId": "sub_456",
"planCode": "BASIC_YEARLY",
"planId": "plan_xyz"
}
]
}Get Subscription by ItemGET
/v1/users/{userRef}/subscriptions/{itemId}
Fetch a specific subscription for a user by item ID.
curl -X GET https://oncade.gg/api/v1/users/user_123/subscriptions/item_456 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"itemId": "item_456",
"status": "Active",
"subscriptionId": "sub_123",
"planCode": "PREMIUM_MONTHLY",
"planId": "plan_abc"
}Approve Account LinkPOST
/v1/users/link/approve
Complete an account link session. Dispatches User.Account.Link.Succeeded on success. If no email is available from the session, one must be provided in the body (400 EMAIL_REQUIRED otherwise).
curl -X POST https://oncade.gg/api/v1/users/link/approve \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 122ae170-30e8-44c3-b42d-c4d03dac9881" \
-H "Content-Type: application/json" \
-d '{
"sessionKey": "session_abc123",
"email": "user@example.com"
}'Example Response
{
"success": true
}Decline Account LinkPOST
/v1/users/link/decline
Decline an in-progress account link session.
curl -X POST https://oncade.gg/api/v1/users/link/decline \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 69a1232a-644c-4e1e-8930-df16283c5b4b" \
-H "Content-Type: application/json" \
-d '{
"sessionKey": "session_abc123"
}'Example Response
{
"success": true
}Remove Account LinkPOST
/v1/users/link/remove
Remove a previously approved link between a player and the game.
curl -X POST https://oncade.gg/api/v1/users/link/remove \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 58aa7449-c0c2-451a-9bd5-89e09152f570" \
-H "Content-Type: application/json" \
-d '{
"user_ref": "user_abc123"
}'Example Response
{
"success": true
}Cancel SubscriptionPOST
/v1/users/{userRef}/subscriptions/{itemId}/cancel
Cancel an active subscription. Works for guest accounts too. Dispatches Subscription.Canceled.
curl -X POST https://oncade.gg/api/v1/users/user_abc123/subscriptions/6565fade4f0d5f25af0a9ab3/cancel \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 8f31675d-f396-432a-bdd7-fc06328d7431"Example Response
{
"success": true,
"subscriptionId": "sub_123"
}List ProductsGET
/v1/products
List products for the game. Supports filtering by status, type, creator, or keyword.
curl -X GET https://oncade.gg/api/v1/products?status=active&type=purchase&q=sword&page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"products": [
{
"_id": "64b10b1cec13f995e9000011",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Sword of Testing",
"description": "Legendary blade for QA heroes.",
"price": 100,
"fulfillmentType": "NONE",
"isVisible": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Get ProductGET
/v1/product/{productId}
Fetch a single product by ID.
curl -X GET https://oncade.gg/api/v1/product/64b10b1cec13f995e9000011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"_id": "64b10b1cec13f995e9000011",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Sword of Testing",
"description": "Legendary blade for QA heroes.",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 100,
"fulfillmentType": "NONE",
"isVisible": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Create Product (SDK)POST
/v1/product
Create a product from your game server. Accepts USD and/or virtual currency pricing. Returns 201.
curl -X POST https://oncade.gg/api/v1/product \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 81fc0d54-c160-4304-8fbd-29570dbe1b1e" \
-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"
}Update Product (SDK)PATCH
/v1/product/{productId}
Update an existing product. All fields are optional.
curl -X PATCH https://oncade.gg/api/v1/product/65fa1234abcdef5678901234 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-d '{
"name": "Premium Sword v2",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 1200,
"virtualCurrencyPrices": "[\n {\n \"currencyId\": \"cur_123\",\n \"amount\": 80\n }\n]",
"forSale": "true"
}'Example Response
{
"_id": "65fa1234abcdef5678901234",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Premium Sword v2",
"description": "A legendary blade",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 1200,
"hasUsdPrice": true,
"virtualCurrencyPrices": [
{
"currencyId": "cur_123",
"amount": 80,
"currency": {
"code": "GEM",
"name": "Gems"
}
}
],
"fulfillmentType": "WEBHOOK",
"isVisible": true,
"isPriceVisible": true,
"forSale": true,
"perUserLimit": 1,
"status": "active",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}Create ProductPOST
/v1/products
Create a product for the game. Returns 201.
curl -X POST https://oncade.gg/api/v1/products \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 887e5a5d-e276-4c7f-9273-b197eddb527c" \
-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,
"purchaseDisplayInfo": "purchase_count",
"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"
}Update Product Sale StatePUT
/v1/products
Enable or disable sales for an existing product.
curl -X PUT https://oncade.gg/api/v1/products \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 92bec864-69bf-4efa-9f50-5fddbd6d71cf" \
-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"
}Create UGC ProductPOST
/v1/products/{userRef}
Create a user-generated product. Created as a hidden draft with sales disabled. Returns 201.
curl -X POST https://oncade.gg/api/v1/products/link_usr_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: a108ca62-5c9b-4da2-8bb7-93ecbc9e03a0" \
-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"
}Submit Product for ReviewPOST
/v1/products/{userRef}/{productId}/submit
Submit a user-generated product for admin review.
curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/submit \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 348fd2a7-8146-4a5e-a314-a4f8ea1e79da"Review ProductPOST
/v1/products/{userRef}/{productId}/review
Approve or decline a submitted product. On approval, you can override pricing and display settings.
curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/review \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: ca2beec5-11b5-42b4-acdf-21435d07777d" \
-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"
}List Creator ProductsGET
/v1/products/{userRef}
List products created by a specific user.
curl -X GET https://oncade.gg/api/v1/products/user_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Get User BalancePOST
/v1/wallet/balance
Return wallet address and balance for a user. Requires Idempotency-Key.
curl -X POST https://oncade.gg/api/v1/wallet/balance \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 09fabf8a-0e8c-48c5-9db3-0d910121b3dc" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_123"
}'Example Response
{
"address": "0xabcDEFabcDEFabcDEFabcDEFabcDEFabcDEFabcd",
"balance": "1500000"
}Get Manage Wallet LinkPOST
/v1/wallet/manage
Generate a profile management link for a user. Requires Idempotency-Key.
curl -X POST https://oncade.gg/api/v1/wallet/manage \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 5b649b1c-db27-482e-98d2-add5d5bae36b" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_123"
}'Example Response
{
"linkUrl": "https://oncade.gg/dashboard/profile"
}Get Wallet PurchaseGET
/v1/wallet/purchase/{purchaseId}
Fetch status and payout details for a wallet purchase.
curl -X GET https://oncade.gg/api/v1/wallet/purchase/purchase_abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"data": {
"_id": "purchase_abc123",
"itemId": "65fa1234abcdef5678901234",
"userId": "507f1f77bcf86cd799439011",
"gameId": "game_123",
"environment": "test",
"status": "pending",
"fulfillmentStatus": "pending",
"priceInCents": 1000,
"taxAmountInCents": 0,
"feeRate": {
"percentage": 10,
"flat": 0
},
"feeName": "walletFee",
"payouts": [
{
"recipient": "creator",
"recipientAddress": "0xCreatorAddress",
"amount": 700
},
{
"recipient": "platform",
"recipientAddress": "0xPlatformAddress",
"amount": 300
}
],
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}Initiate Virtual Currency PurchasePOST
/v1/vc/purchases
Start a virtual currency purchase. Returns 201 with the amount to debit and a link to the complete endpoint.
curl -X POST https://oncade.gg/api/v1/vc/purchases \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 0a501c3a-bd12-4a2f-95f6-01f8e99fedbd" \
-H "Content-Type: application/json" \
-d '{
"userId": "link_usr_123",
"itemId": "65fa1234abcdef5678901234",
"currencyId": "cur_abc123",
"affiliateCode": "STREAMER123",
"dealCode": "GEMS_SALE",
"metadata": {
"campaign": "spring"
}
}'Example Response
{
"data": {
"purchaseId": "purchase_abc123",
"currencyId": "cur_abc123",
"amountUnits": "800"
}
}Complete Virtual Currency PurchasePOST
/v1/vc/purchases/{purchaseId}
Complete a virtual currency purchase. Debits the balance and triggers fulfillment. Idempotent via Idempotency-Key.
curl -X POST https://oncade.gg/api/v1/vc/purchases/purchase_abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: a48233ba-d66d-4879-8131-20ff3872922a"Example Response
{
"data": {
"purchaseId": "purchase_abc123",
"journalId": "txn_xyz789",
"newBalanceUnits": "9000",
"purchase": {
"_id": "purchase_abc123",
"status": "completed",
"isPaid": true,
"fulfillmentStatus": "completed"
}
}
}Create Affiliate LinkPOST
/v1/affiliate-links
Create or return an affiliate short code for a user. Idempotent.
curl -X POST https://oncade.gg/api/v1/affiliate-links \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 0484581a-d0c7-4836-ac9f-98b16e18c69a" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_abc123",
"itemId": "65fa1234abcdef5678901234"
}'Example Response
{
"shortCode": "abc123"
}Get Affiliate LinkGET
/v1/affiliate-links/{shortCode}
Fetch details and stats for a single affiliate link by short code.
curl -X GET https://oncade.gg/api/v1/affiliate-links/abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"shortCode": "abc123",
"gameId": "game_123",
"environment": "test",
"campaign": null,
"clickCount": 42,
"conversionCount": 5,
"pageViewCount": 120,
"startSessionCount": 15,
"totalEarnings": 2500,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-15T00:00:00.000Z",
"lastClickedAt": "2026-01-15T12:00:00.000Z"
}Register Affiliate ConversionPOST
/v1/affiliate-links/{shortCode}/convert
Record a conversion against an affiliate link. Optionally credit virtual currency to the affiliate. Requires Idempotency-Key.
curl -X POST https://oncade.gg/api/v1/affiliate-links//convert \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 2b971a29-82e4-4aed-ae6d-768e1c1163c9" \
-H "Content-Type: application/json" \
-d '{
"earningsCents": 500,
"vcCreditAmount": "100",
"currencyId": "cur_123"
}'Example Response
{
"conversionCount": 3,
"vcCredit": {
"journalId": "jrnl_001",
"newBalanceUnits": "1500",
"currencyId": "cur_123"
}
}Create Ghost Affiliate LinkPOST
/v1/affiliate-links/ghost
Create an affiliate link for an external player who does not have an Oncade account. A ghost user is created automatically. Idempotent — returns the existing link if one already exists for the same player and campaign. Requires Idempotency-Key.
curl -X POST https://oncade.gg/api/v1/affiliate-links/ghost \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 75351325-d854-4aa2-87c2-d2320edd1a92" \
-H "Content-Type: application/json" \
-d '{
"externalPlayerId": "player-abc",
"campaign": "summer2026"
}'Example Response
{
"shortCode": "ABC123",
"userRef": "link_usr_abc123",
"created": true
}List Ghost Affiliate LinksGET
/v1/affiliate-links/ghost
List affiliate links with pagination. Optionally filter by external player ID.
curl -X GET https://oncade.gg/api/v1/affiliate-links/ghost?externalPlayerId=player-abc&page=1&limit=10 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"data": [
{
"shortCode": "ABC123",
"gameId": "game_123",
"environment": "test",
"campaign": "summer2026",
"clickCount": 5,
"conversionCount": 2,
"pageViewCount": 10,
"totalEarnings": 500,
"createdAt": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Get Checkout ThemeGET
/v1/checkout/theme
Return the checkout theme for a game. Falls back to store theme colors if no game theme is set.
curl -X GET https://oncade.gg/api/v1/checkout/theme?gameId=test-game&itemId=65fa1234abcdef5678901234 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"primaryButtonColor": "#3B82F6",
"secondaryButtonColor": "#22C55E",
"notifyButtonColor": "#374151",
"backgroundColor": "#1F2937",
"borderColor": "#374151",
"priceOverrideColor": "#4ade80",
"logoUrl": "https://cdn.oncade.com/logos/game.png"
}Get Store Checkout URLGET
/v1/checkout/redirect
Return a storefront checkout URL for an item. Use checkoutMethod to auto-select a payment method. Returns 400 for invalid deal codes, 410 if the item is not for sale.
curl -X GET https://oncade.gg/api/v1/checkout/redirect?gameId=test-game&itemId=65fa1234abcdef5678901234&checkoutmethod=credit \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"status": 200,
"headers": {
"Location": "https://oncade.gg/games/test-game/items/65fa1234abcdef5678901234?mode=api&checkoutmethod=credit"
},
"body": {
"url": "https://oncade.gg/games/test-game/items/65fa1234abcdef5678901234?mode=api&checkoutmethod=credit"
}
}Create Checkout GrantPOST
/v1/checkout/grants
Create a signed checkout grant so players can purchase without authenticating on Oncade first. Returns a one-time checkout URL (expires after 2 hours). If no userRef is provided, one is generated or looked up by email. The same email always resolves to the same userRef per game.
curl -X POST https://oncade.gg/api/v1/checkout/grants \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 5afb59bc-c741-4619-89f3-93d6eef3578e" \
-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"
}List Split TemplatesGET
/v1/split-templates
List non-archived split templates for the business, newest first.
curl -X GET https://oncade.gg/api/v1/split-templates \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"templates": [
{
"_id": "64b10b1cec13f995e9000011",
"name": "Team Revenue Split",
"description": "Default split for team revenue sharing",
"businessId": "64b10b1cec13f995e9000012",
"createdBy": "usr_123",
"recipients": [
{
"email": "dev1@example.com",
"name": "Developer 1",
"percentage": 50
},
{
"email": "dev2@example.com",
"name": "Developer 2",
"percentage": 30
},
{
"email": "dev3@example.com",
"name": "Developer 3",
"percentage": 20
}
],
"isArchived": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
],
"total": 1
}Create Split TemplatePOST
/v1/split-templates
Create a split template. Recipient percentages must sum to 100%. Names must be unique per business. Returns 201.
curl -X POST https://oncade.gg/api/v1/split-templates \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 3e8d9c3b-9c9e-44a0-8972-f6190d600962" \
-H "Content-Type: application/json" \
-d '{
"name": "Team Revenue Split",
"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",
"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"
}Get Split TemplateGET
/v1/split-templates/{templateId}
Fetch a split template by ID.
curl -X GET https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"_id": "64b10b1cec13f995e9000011",
"name": "Team Revenue Split",
"description": "Default split for team revenue sharing",
"businessId": "64b10b1cec13f995e9000012",
"createdBy": "usr_123",
"recipients": [
{
"email": "dev1@example.com",
"name": "Developer 1",
"percentage": 50
},
{
"email": "dev2@example.com",
"name": "Developer 2",
"percentage": 30
},
{
"email": "dev3@example.com",
"name": "Developer 3",
"percentage": 20
}
],
"isArchived": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Update Split TemplatePUT
/v1/split-templates/{templateId}
Update a split template. All fields optional. If recipients change, percentages must still sum to 100%.
curl -X PUT https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 9e0cca9a-e6ed-4535-8fb6-ae4c2493e7e7" \
-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",
"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"
}Get Split Template Redirect URLGET
/v1/split-templates/{templateId}/redirect
Return a redirect URL to the DevPortal distribution page with this template pre-loaded.
curl -X GET https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011/redirect?amount=1000 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"url": "https://dev.oncade.gg/dashboard/business/team-payouts/distribute?templateId=64b10b1cec13f995e9000011&amount=1000"
}Create Ghost UserPOST
/v1/platform/vc/users
Create a ghost user for virtual currency operations. If an email is provided, the call is idempotent — the same email always resolves to the same user. Returns 409 if the email belongs to an existing authenticated user. Requires platform API key with vc:user:create scope.
curl -X POST https://oncade.gg/api/v1/platform/vc/users \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 326eb82b-87a7-44ed-be4a-ab7fb9b3f936" \
-H "Content-Type: application/json" \
-d '{
"email": "player@example.com"
}'Example Response
{
"userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d"
}Get User VC Balance (Platform)GET
/v1/platform/vc/balances
Fetch a user's virtual currency balance. Requires platform API key with vc:balance:read scope, X-Target-Business-Id, and X-Game-Id headers.
curl -X GET https://oncade.gg/api/v1/platform/vc/balances?currencyId=cur_123&userId=pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"currencyId": "cur_123",
"userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
"balanceUnits": "500",
"updatedAt": "2024-05-01T00:00:00.000Z"
}Credit VC Balance (Platform)POST
/v1/platform/vc/credits
Credit virtual currency to a user via platform API key. Requires vc:credit scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.
curl -X POST https://oncade.gg/api/v1/platform/vc/credits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: ad6fe53e-3edc-4030-bb44-fba740f2996a" \
-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"
}Debit VC Balance (Platform)POST
/v1/platform/vc/debits
Debit virtual currency from a user via platform API key. Requires vc:debit scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.
curl -X POST https://oncade.gg/api/v1/platform/vc/debits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: ec55e4d5-038f-4b79-bb61-00beb7d7df9b" \
-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"
}Batch VC Transfer (Platform)POST
/v1/platform/vc/batch
Atomically debit one user and distribute to multiple recipients via platform API key. Requires vc:batch scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.
curl -X POST https://oncade.gg/api/v1/platform/vc/batch \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 7f660018-9640-4b3b-93ff-7b2a5a469f6a" \
-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"
}Purchase Item with VC (Platform)POST
/v1/platform/vc/purchases
Purchase an item using virtual currency on behalf of a user. Debits the user's balance and records the purchase. Supports idempotency — replaying the same Idempotency-Key returns the original result. Requires platform API key with vc:purchase scope, X-Target-Business-Id, X-Game-Id, and Idempotency-Key headers.
curl -X POST https://oncade.gg/api/v1/platform/vc/purchases \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 42b51e8d-d337-4e20-a2b6-8a2083b51754" \
-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"
}
}List User Purchases (Platform)GET
/v1/platform/vc/users/{userRef}/purchases
List completed virtual currency purchases for a user. Supports pagination and filtering by game, currency, and date range. Requires platform API key with vc:purchase:read scope, X-Target-Business-Id, and X-Game-Id headers.
curl -X GET https://oncade.gg/api/v1/platform/vc/users/pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d/purchases?page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "507f1f77bcf86cd799439033",
"platformUserId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
"gameId": "game_001",
"itemId": "507f1f77bcf86cd799439011",
"itemName": "Gold Sword",
"currencyId": "507f1f77bcf86cd799439022",
"unitPrice": "500",
"quantity": 1,
"totalAmountUnits": "500",
"journalId": "jrnl_004",
"status": "completed",
"createdAt": "2025-01-15T10:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Create Affiliate Link (Platform)POST
/v1/platform/affiliate-links
Create an affiliate tracking link for the authenticated platform. Returns a short code that can be used to build tracking URLs. Requires platform API key with affiliateLink:create scope.
curl -X POST https://oncade.gg/api/v1/platform/affiliate-links \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 910df40d-9719-4a52-b9e1-a1ecdf3d9be4" \
-H "Content-Type: application/json" \
-d '{
"label": "Summer Campaign"
}'Example Response
{
"shortCode": "abc123",
"label": "Summer Campaign",
"clickCount": 0,
"conversionCount": 0,
"pageViewCount": 0,
"createdAt": "2025-01-15T10:00:00.000Z"
}List Affiliate Links (Platform)GET
/v1/platform/affiliate-links
List all affiliate tracking links for the authenticated platform, sorted by creation date (newest first). Requires platform API key with affiliateLink:read scope.
curl -X GET https://oncade.gg/api/v1/platform/affiliate-links \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"links": [
{
"shortCode": "abc123",
"label": "Summer Campaign",
"clickCount": 42,
"conversionCount": 5,
"pageViewCount": 100,
"startSessionCount": 12,
"createdAt": "2025-01-15T10:00:00.000Z"
}
]
}Record Gameplay Event (Platform)POST
/v1/platform/gameplay/events
Record a gameplay event (e.g. gameplay minutes, achievements) for a platform user. Uses idempotency key to prevent duplicate recording. Requires platform API key with gameplay:event:create scope.
curl -X POST https://oncade.gg/api/v1/platform/gameplay/events \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: ddfab0be-18cd-4043-a2b6-7ae286070649" \
-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
}Create Item (Platform)POST
/v1/platform/items
Create a new game item in the catalog. The item is created with isVisible=false (platform items are never shown on the public storefront). Supports USD pricing, virtual currency pricing, or both. Requires platform API key with item:create scope, X-Target-Business-Id header, and Idempotency-Key header.
curl -X POST https://oncade.gg/api/v1/platform/items \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: a1b46e19-cddc-40f1-b10b-6bc1516ade54" \
-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"
}List Items (Platform)GET
/v1/platform/items
List all items for a game with pagination. Returns items sorted by creation date (newest first). Requires platform API key with item:read scope and X-Target-Business-Id header.
curl -X GET https://oncade.gg/api/v1/platform/items?gameId=game_001&page=1&limit=50 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "507f1f77bcf86cd799439011",
"gameId": "game_001",
"name": "Gold Sword",
"type": "consumable",
"hasUsdPrice": false,
"price": 0,
"virtualCurrencyPrices": [
[
"507f1f77bcf86cd799439022",
500
]
],
"fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
"forSale": true,
"isVisible": false,
"createdAt": "2025-01-15T10:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1
}
}Get Item (Platform)GET
/v1/platform/items/{itemId}
Retrieve a single item by ID. The item must belong to a game owned by the target business. Requires platform API key with item:read scope and X-Target-Business-Id header.
curl -X GET https://oncade.gg/api/v1/platform/items/507f1f77bcf86cd799439011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"_id": "507f1f77bcf86cd799439011",
"gameId": "game_001",
"name": "Gold Sword",
"type": "consumable",
"description": "A powerful golden sword",
"hasUsdPrice": false,
"price": 0,
"virtualCurrencyPrices": [
[
"507f1f77bcf86cd799439022",
500
]
],
"fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
"forSale": true,
"isVisible": false,
"perUserLimit": 0,
"createdAt": "2025-01-15T10:00:00.000Z",
"updatedAt": "2025-01-15T10:00:00.000Z"
}Update Item (Platform)PATCH
/v1/platform/items/{itemId}
Update an existing item. Only provided fields are modified — omitted fields remain unchanged. The item must belong to a game owned by the target business. Requires platform API key with item:update scope and X-Target-Business-Id header.
curl -X PATCH https://oncade.gg/api/v1/platform/items/ \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-d '{
"name": "Diamond Sword",
"virtualCurrencyPrices": "[\n [\n \"507f1f77bcf86cd799439022\",\n 750\n ]\n]",
"forSale": "true"
}'Example Response
{
"_id": "507f1f77bcf86cd799439011",
"gameId": "game_001",
"name": "Diamond Sword",
"type": "consumable",
"description": "A powerful golden sword",
"hasUsdPrice": false,
"price": 0,
"virtualCurrencyPrices": [
[
"507f1f77bcf86cd799439022",
750
]
],
"fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
"forSale": true,
"isVisible": false,
"perUserLimit": 0,
"createdAt": "2025-01-15T10:00:00.000Z",
"updatedAt": "2025-01-15T12:00:00.000Z"
}Archive Item (Platform)DELETE
/v1/platform/items/{itemId}
Archive an item by setting forSale=false and isVisible=false. The item is not permanently deleted. Requires platform API key with item:archive scope and X-Target-Business-Id header.
curl -X DELETE https://oncade.gg/api/v1/platform/items/507f1f77bcf86cd799439011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
null
List Gameplay Rollups (Platform)GET
/v1/platform/gameplay/rollup
List gameplay rollups for the platform, optionally filtered by status. If a period query param is provided, returns the single rollup for that period instead of a list. Requires platform API key with gameplay:rollup:read scope.
curl -X GET https://oncade.gg/api/v1/platform/gameplay/rollup?status=draft \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"rollups": [
{
"_id": "507f1f77bcf86cd799439011",
"platformId": "plat_001",
"businessId": "507f1f77bcf86cd799439022",
"period": "2026-05",
"status": "draft",
"totalMinutes": 1200,
"games": [
{
"gameId": "game_001",
"gameName": "Space Blasters",
"minutes": 720,
"share": 0.6,
"skuId": null,
"skuDisplayName": null
},
{
"gameId": "game_002",
"gameName": "Puzzle Quest",
"minutes": 480,
"share": 0.4,
"skuId": null,
"skuDisplayName": null
}
],
"createdAt": "2026-06-01T00:00:00.000Z",
"updatedAt": "2026-06-01T00:00:00.000Z"
}
],
"total": 1
}Generate Gameplay Rollup (Platform)POST
/v1/platform/gameplay/rollup
Generate a gameplay rollup for a given period. Aggregates all gameplay_minutes events for the platform during that month into a per-game breakdown. If a draft rollup already exists for the period it is overwritten; if a confirmed rollup exists the request is rejected. Requires platform API key with gameplay:rollup:generate scope.
curl -X POST https://oncade.gg/api/v1/platform/gameplay/rollup \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: e85e7a07-fa47-47af-85bf-f5a1202655bd" \
-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"
}
}Confirm Gameplay Rollup (Platform)POST
/v1/platform/gameplay/rollup/confirm
Confirm a draft gameplay rollup for a given period. Once confirmed, the rollup cannot be regenerated. This endpoint only changes the rollup status — to create a distribution from the confirmed rollup, use the Pay dashboard. Requires platform API key with gameplay:rollup:confirm scope.
curl -X POST https://oncade.gg/api/v1/platform/gameplay/rollup/confirm \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 5ddda84e-a082-40a7-b0b1-188471b540d6" \
-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"
}
}