Skip to main content

Gacha Machine API Documentation

๐ŸŽฎ Demo Repository: Check out the Gacha Starter Demo for a working example implementation.

Overviewโ€‹

The gacha machine API allows users to purchase mystery packs containing NFTs, open them to receive random NFTs, and optionally sell them back for USDC. This guide covers the standard $50 pack flow.

Devnet USDC Faucetโ€‹

Use this faucet to get the USDC token used on devnet: https://spl-token-faucet.com/?token-name=USDC-Dev

Devnetโ€‹

You can see all of the API calls in action on the live devnet site: https://dev-gacha.collectorcrypt.com

๐Ÿ” Authenticationโ€‹

Send x-api-key on every request.

It is not an access gate on the play endpoints. A missing or invalid key is not rejected โ€” the request is simply treated as unauthenticated and your memo prefix falls back to cc-, so those packs are not attributable to you and slug will not find them. A typo therefore fails silently rather than erroring. The routes that do hard-fail with 401 on a missing or invalid key are /api/v1/machines and /api/v1/stock.

Why It Mattersโ€‹

  • Tags your transactions with a memo prefix unique to your key.
  • Scopes /api/v1/* and your private machines to your key.
  • Lets you filter all pack/send/buyback activity by your key using the slug query parameter.

Example Headerโ€‹

curl -X POST "https://gacha.collectorcrypt.com/api/generatePack" \
-H "Content-Type: application/json" \
-H "x-api-key: API_KEY" \
-d '{
"playerAddress": "HWPRgtDGpBm8mByTGS57BWCsijMo53qPPSbskWDukfTc"
}'

Endpointsโ€‹

Transactions can be submitted directly to the blockchain after they've been signed.

Generate Pack - /api/generatePackโ€‹

Creates a transaction for purchasing a pack. The user needs to sign this transaction to begin the purchase. Generates a partially signed transaction that transfers 50 USDC from the player to the gacha wallet. Returns a unique memo identifier and the transaction that needs to be signed by the player.

Method: POST

Request Body:

{
"playerAddress": "wallet_public_key",
"packType": "pokemon_50", // optional, defaults to "pokemon_50"; use "pokemon_250" for legendary packs
"turbo": true, // optional; when true, Common wins are auto-sold during openPack
"altPlayerAddress": "wallet_public_key", // optional; the won card is sent to this wallet instead of playerAddress
"altFundsRecipient": "wallet_public_key", // optional, turbo only; the auto-sell USDC is sent here instead of the card recipient
"token": "USDC", // optional, defaults to USDC; the payment token, as a symbol or mint address (see below)
"coinflowCredits": true // optional; build the transaction for a Coinflow credits redeem (see below)
}

Payment token: leave token out to pay in USDC. A value that is not accepted is not rejected: the pack is priced in USDC, so check the spelling. A buyback of a card from the pack, including a turbo auto-sell, pays in the token the pack was bought with.

Response:

{
"memo": "slug-uuid",
"transaction": "base64_encoded_transaction"
}

Error Responses:

  • 400: Invalid request body, player address, alt player address, or alt funds recipient; or coinflowCredits with a non-USDC token or with spearfishNfts
  • 403: Player address, alt player address, or alt funds recipient is blocked
  • 500: Machine error โ€” the details field gives the cause:
    • Machine is off balance โ€” pool expected value is temporarily above the cap; retry shortly or try another machine
    • Machine is empty (non-turbo) / Machine is low (turbo) โ€” a prize tier is low on inventory
    • Machine is off โ€” machine toggled off or emergency stop active
  • 429: Backlog guard, counted per buyer wallet (playerAddress), not per API key:
    • Too many pending packs. Complete a purchase to continue. โ€” more than 50 generatePack calls from this wallet in 10 minutes with none of them paid for. Clears as soon as one of them is paid for. The Retry-After header gives the seconds until it clears without a payment.
    • Too many open packs โ€” more than 30 paid-but-unopened non-turbo packs for this wallet and pack type in the last 2 hours. Clears as they are opened. Turbo packs are exempt.
  • 503: Machine has too many packs currently open (retry shortly)

Note: turbo mode will automatically process a buyback for Common wins when calling /api/openPack.

Paying with Coinflow credits: if your buyers pay with credits from your own Coinflow merchant account, pass "coinflowCredits": true and keep the default USDC token. On devnet pass "token": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU" instead, the USDC that Coinflow sandbox redeems into; with the default devnet USDC, /api/redeem refuses with "No approved program in transaction". The returned transaction then has the gacha wallet as fee payer and needs no gacha signature after wrapping, so Coinflow can swap in its own fee payer. Send it to Coinflow unchanged (full curl in the Coinflow credits example):

  1. POST /api/redeem on Coinflow with your merchant's session key, x-coinflow-auth-wallet: <playerAddress>, x-coinflow-auth-blockchain: solana, and body { merchantId, subtotal: { cents: <pack price ร— 100>, currency: "USD" }, transaction: <the transaction, base58> }.
  2. Have the player sign the transaction Coinflow returns, then send it with Coinflow's POST /api/utils/send-coinflow-tx.
  3. Call /api/openPack with the memo. It returns WAITING_FOR_WEBHOOK until our webhook sees the USDC land in the gacha wallet (a few seconds); keep polling.

Do not send a credits redeem through /api/submitTransaction. Your Coinflow merchant must allow-list the gacha wallet's USDC token account D9CEogjHA6CpS12F8St9zpSco7pQKJB5uR1RqDsuzQZk (on your sandbox merchant for devnet: 3zzF24fJKkyyhwxazGk5yTxfCbV5JQw8zfLJbphww1Fe) with Coinflow POST /api/merchant/program or the dashboard's Whitelist Program page, or /api/redeem refuses with "not whitelisted" or "No approved program in transaction". Always pass coinflowCredits for a redeem: without it, a player holding 0.01 SOL or more gets a transaction that needs a gacha signature, and Coinflow's wrap changes the transaction so that signature no longer verifies.

Funds split (turbo only): by default the auto-sell USDC and any non-Common card both go to altPlayerAddress (or playerAddress if it's unset). Provide altFundsRecipient to send the auto-sell USDC to a separate address while non-Common cards still go to altPlayerAddress. Recall that in turbo a given pack pays out either USDC (Common, auto-sold) or a card (non-Common) โ€” never both โ€” so altFundsRecipient only affects Common wins. It is ignored for non-turbo packs.

Coinflow credits exampleโ€‹

A credits pack on devnet, paid through Coinflow sandbox. Replace API_KEY with your gacha API key, COINFLOW_API_KEY with your Coinflow sandbox API key, MERCHANT_ID with your Coinflow merchant id, and wallet_public_key with the buyer's wallet. On mainnet, use https://api.coinflow.cash and https://gacha.collectorcrypt.com, leave out token, and allow-list D9CEogjHA6CpS12F8St9zpSco7pQKJB5uR1RqDsuzQZk instead.

1. Allow-list the gacha's token account (once per merchant):

curl -X POST "https://api-sandbox.coinflow.cash/api/merchant/program" \
-H "Content-Type: application/json" \
-H "Authorization: COINFLOW_API_KEY" \
-d '{
"blockchain": "solana",
"programId": "3zzF24fJKkyyhwxazGk5yTxfCbV5JQw8zfLJbphww1Fe"
}'

2. Generate the pack:

curl -X POST "https://dev-gacha.collectorcrypt.com/api/generatePack" \
-H "Content-Type: application/json" \
-H "x-api-key: API_KEY" \
-d '{
"playerAddress": "wallet_public_key",
"packType": "pokemon_50",
"coinflowCredits": true,
"token": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"
}'

Returns memo and transaction.

3. Get a Coinflow session key for the buyer:

curl "https://api-sandbox.coinflow.cash/api/auth/session-key" \
-H "Authorization: COINFLOW_API_KEY" \
-H "x-coinflow-auth-wallet: wallet_public_key" \
-H "x-coinflow-auth-blockchain: solana"

Returns { "key": "session_key" }.

4. Redeem the credits:

curl -X POST "https://api-sandbox.coinflow.cash/api/redeem" \
-H "Content-Type: application/json" \
-H "Authorization: COINFLOW_API_KEY" \
-H "x-coinflow-auth-wallet: wallet_public_key" \
-H "x-coinflow-auth-blockchain: solana" \
-H "x-coinflow-auth-session-key: session_key" \
-d '{
"merchantId": "MERCHANT_ID",
"subtotal": { "cents": 5000, "currency": "USD" },
"transaction": "base58_encoded_transaction"
}'

transaction is the one from step 2, converted from base64 to base58. cents is the pack price ร— 100. Returns { "transaction": "base58_encoded_transaction" }. A 412 means the buyer has too few credits on your merchant.

5. Have the buyer sign the returned transaction, then send it:

curl -X POST "https://api-sandbox.coinflow.cash/api/utils/send-coinflow-tx" \
-H "Content-Type: application/json" \
-H "Authorization: COINFLOW_API_KEY" \
-d '{
"merchantId": "MERCHANT_ID",
"signedTransaction": "base58_encoded_signed_transaction",
"confirm": true
}'

6. Open the pack:

curl -X POST "https://dev-gacha.collectorcrypt.com/api/openPack" \
-H "Content-Type: application/json" \
-H "x-api-key: API_KEY" \
-d '{
"memo": "slug-uuid"
}'

Repeat while it returns WAITING_FOR_WEBHOOK.


Generate Yolo Packs - /api/generateYoloPacksโ€‹

Creates multiple transactions for purchasing multiple packs at once. Each pack gets its own transaction and memo that needs to be signed individually by the player.

Method: POST

Request Body:

{
"count": 2,
"packType": "pokemon_50",
"playerAddress": "5Kp9FbQ2oEKt6XnEvbovsnkpewW3wm9bg4ff3c3hAPbt",
"turbo": true, // optional; applies to all generated packs, auto-sells Common wins during openPack
"altPlayerAddress": "wallet_public_key", // optional; the won NFT is sent to this wallet instead of playerAddress
"altFundsRecipient": "wallet_public_key", // optional, turbo only; auto-sell USDC for Common wins is sent here instead of the NFT recipient (applies to every pack in the batch)
"token": "USDC" // optional, defaults to USDC; same as /api/generatePack, applies to every pack in the batch
}

Response:

{
"yoloId": "uuid",
"count": 2,
"transactions": [
{
"memo": "slug-uuid-1",
"transaction": "base64_encoded_transaction_1"
},
{
"memo": "slug-uuid-2",
"transaction": "base64_encoded_transaction_2"
}
]
}

Error Responses:

  • 400: Invalid request body, player address, or count (must be between 1 and 100)
  • 403: Player, alt player, or alt funds recipient address is blocked
  • 500: Machine error โ€” the details field gives the cause:
    • Machine is off balance โ€” pool expected value is temporarily above the cap; retry shortly or try another machine
    • Machine is low โ€” a prize tier is low on inventory
    • Machine is off โ€” machine toggled off or emergency stop active

What it does: Generates multiple pack purchase transactions at once (up to 100). Each transaction must be signed separately using /api/submitTransaction, then each memo can be used with /api/openPack to receive the NFTs.

Note: When turbo is true, all generated packs will auto-sell Common wins during /api/openPack.


Open Pack - /api/openPackโ€‹

Opens a purchased pack and sends an NFT to the player. The VRF roll picks the prize tier from the machine's configured rarity weights (each machine has its own odds, so call /api/machines to read the live odds per machine), then a provable selection picks the card within that tier โ€” see Provable Fairness (VRF). The NFT is transferred to the player and the metadata returned. For turbo mode with low-tier wins, automatically processes a buyback.

Method: POST

Request Body:

{
"memo": "slug-uuid-string"
}

Response (Success):

{
"success": true,
"transactionSignature": "nft_transfer_transaction_hash",
"nft_address": "nft_mint_address",
"nftWon": {
"content": {
"metadata": {
"name": "Card Name",
"description": "Card Description",
"attributes": [...]
}
}
},
"points": 0,
"roll": 12345678,
"vrfProof": "0x_vrf_proof_hex",
"insuredValue": 250,
"rarity": "Epic"
}

rarity is one of "Epic", "Rare", "Uncommon", or "Common". insuredValue is the card's insured value in whole dollars. vrfProof is the VRF proof behind roll, as 0x-prefixed hex; see Provable Fairness (VRF).

Response (Turbo Mode Buyback): When turbo mode is enabled and the pack rolls Common, the NFT is auto-sold for USDC and the response includes additional fields:

{
"success": true,
"transactionSignature": "nft_transfer_transaction_hash",
"nft_address": "nft_mint_address",
"nftWon": { /* NFT metadata */ },
"points": 0,
"code": "TURBO_MODE_BUYBACK",
"buybackAmount": 42500000,
"roll": 87654321,
"vrfProof": "0x_vrf_proof_hex",
"insuredValue": 50,
"rarity": "Common"
}

buybackAmount is the auto-sell payout in USDC base units (6 decimals; e.g. 42500000 = 42.5 USDC). The USDC is sent to altFundsRecipient if it was supplied at /api/generatePack (or /api/generateYoloPacks), otherwise to altPlayerAddress, otherwise to playerAddress.

Response (Waiting for Payment): The payment is not confirmed yet, or another /api/openPack call for the same memo is still picking and sending the card.

{
"success": true,
"code": "WAITING_FOR_WEBHOOK",
"memo": "slug-uuid-string"
}

This is not a failure and not an empty machine. Call /api/openPack again with the same memo after about a second: it never sends a second card, and once the send is recorded it returns the full award (see Already Opened below). A reply with success: true always carries either nft_address or a code.

Response (Already Opened): Returns success, transactionSignature, nft_address, nftWon, points, vrfProof, insuredValue and rarity, plus code: "TURBO_MODE_BUYBACK" for any turbo pack and buybackAmount when that turbo pack won a Common and its buyback row still exists. Two differences from the first response: roll is not included, and buybackAmount comes back as a string. Read the roll as actualRoll from /api/vrf/verify?memo=<memo>.

Deadline: an unopened pack must be opened within 2 hours of /api/generatePack. After that /api/openPack returns 400 No spin transaction found for memo permanently, and a paid-but-unopened pack becomes eligible for auto-refund from 2h10m old, processed on the next hourly refund run. This applies only to packs that were never opened โ€” a memo that already has an award keeps returning that award indefinitely.

Error Responses:

  • 400: No spin transaction found (unknown memo, or the pack is past the 2-hour deadline) or no NFTs available
  • 403: Recipient address is blocked
  • 404: No on-chain purchase transaction found for this memo (not yet confirmed)
  • 500: Machine empty or processing error

Buyback - /api/buybackโ€‹

Generates a transaction to sell an NFT back for a percentage of its insured value in USDC. Verifies the NFT was sent out by the gacha within the last 72 hours and has no confirmed buyback yet, then creates a transaction that transfers the NFT back to the original prize wallet and sends USDC to the player (or to altRecipient if provided). Eligibility is NFT-scoped โ€” the caller does not have to be the original winner, though the seller must still sign the transfer. The transaction needs to be signed by the player and submitted to the blockchain.

Method: POST

Request Body:

{
"playerAddress": "wallet_public_key",
"nftAddress": "nft_mint_address",
"altRecipient": "wallet_public_key", // optional; if provided, USDC refund is sent here instead of playerAddress
"transferAuthority": "wallet_public_key" // optional; a delegate that signs the card transfer instead of playerAddress
}
  • transferAuthority: for a card held by a wallet that cannot sign itself, such as a vault with a transfer delegate. The delegate signs the transaction in place of playerAddress; playerAddress is still the card's owner.
  • sellerProgram: switches the request to a signed quote for a program-owned wallet instead of a transaction; see cc_buyback.

Response:

{
"success": true,
"serializedTransaction": "base64_encoded_transaction",
"refundAmount": 42500000,
"memo": "original-memo-string",
"transactionSignature": "base58_transaction_signature"
}

transactionSignature is the signature this transaction will have on-chain, given before you sign it. It is the value /api/pack/status returns as buyback[].transaction_signature for this attempt, so you can match each request to its row. Each request builds its own transaction, so each attempt has its own signature.

Error Responses:

  • 400: Invalid addresses, NFT not found, or outside 72-hour buyback window
  • 403: Player or alt recipient address is blocked; or {"error": "This wallet does not hold the card", "code": "NOT_OWNER"} when playerAddress does not hold the card
  • 409: {"error": "This card is no longer valid and cannot be sold back", "code": "CARD_INVALID"} when Collector Crypt has invalidated the card
  • 500: Transaction building failed

Bulk Buyback - /api/buyback/bulkโ€‹

Builds buyback transactions for several NFTs in one request. It runs the /api/buyback logic once per NFT, so eligibility and price are the same as for a single buyback, and each NFT gets its own transaction partially signed by the gacha wallet.

Method: POST

Request Body:

{
"playerAddress": "wallet_public_key",
"nftAddresses": ["nft_mint_address_1", "nft_mint_address_2"], // 1 to 100 entries; duplicates count toward the 100, and each distinct NFT gets one result
"altRecipient": "wallet_public_key", // optional; if provided, every USDC refund is sent here instead of playerAddress
"transferAuthority": "wallet_public_key" // optional; signs every card transfer instead of playerAddress, as on /api/buyback
}

Response:

{
"results": [
{
"nftAddress": "nft_mint_address_1",
"success": true,
"httpStatus": 200,
"serializedTransaction": "base64_encoded_transaction",
"refundAmount": 42500000,
"memo": "original-memo-string",
"transactionSignature": "base58_transaction_signature"
},
{
"nftAddress": "nft_mint_address_2",
"success": false,
"httpStatus": 400,
"error": "No matching NFT found within the allowed time window"
}
]
}

results has one entry per distinct NFT, in request order. A failed NFT does not change the other entries: the response is 200 whenever the request body is valid, and each entry reports its own outcome.

  • A successful entry has the /api/buyback response fields plus nftAddress and httpStatus.
  • A failed entry has success: false, httpStatus, and the error body /api/buyback returned for that NFT (error, plus code where one is given). httpStatus is the status /api/buyback would have returned, for example 400 outside the buyback window or 403 for a blocked address. 504 means the NFT was not finished within the request's 12-second budget; request it again.

Signing and submitting: sign all the transactions in one wallet prompt (for example signAllTransactions), then submit them all at once: one /api/submitTransaction call per transaction, in parallel (for example with Promise.all). Do not submit them one after another. Each call returns only after its transaction confirms, usually a second or more, so a sequential loop runs the later transactions past their blockhash.

Each transaction is valid for 150 blocks after its blockhash, about 30 seconds on mainnet, and part of that time is gone before you receive it: the blockhash can be up to 10 seconds old when the transaction is built, and the response waits for the whole batch, up to 12 seconds. If a submission comes back 400 with code: "BLOCKHASH_EXPIRED", request that NFT again to get a fresh transaction. Only one transaction per card can ever settle: the card moves once, and the USDC payout is in the same transaction as the card transfer.

Adding sellerProgram returns one quote per NFT instead of a transaction, exactly as /api/buyback does; see cc_buyback.

Error Responses:

  • 400: Invalid JSON; playerAddress missing, not a string, or longer than 44 characters; altRecipient, transferAuthority or sellerProgram given (not null) but not a string of at most 44 characters; or nftAddresses not an array of 1 to 100 non-empty strings of at most 44 characters

Only type and length are checked here. A string that is not a valid Solana address still gets a 200, and each NFT's entry in results carries the error /api/buyback returned for it. sellerProgram is a mode switch and its value is never checked: any non-empty string returns quotes.


Buyback Check - /api/buyback/checkโ€‹

Checks if an NFT buyback has completed.

Method: GET

Query Parameters:

  • memo (required): The memo from the original pack purchase

Example Request:

GET /api/buyback/check?memo=953cc94e-fd51-4f5f-bbcc-5a35faf7df65

Response (Buyback Exists):

{
"exists": true,
"playerWallet": "GfFAJnHnSgP7C2FQZLz6ogpdTV6Y7259f83qFFm9wxKm",
"nft": "H9ZXYkudxn6qhyp5S25jm5SrA8Vnu8naSfvymm9TptLA",
"transactionSignature": "3Dq2kH65vqEzpBKczyDLzNYS8sXmtS5GS9MYTwjVaPM4tqVxjtPGnQG4mKpSPa5iTzqomhFgo9nYs3grRNPp68Fh",
"buybackAmount": "90000",
"createdAt": "2025-05-26T17:32:33.588Z",
"status": "complete"
}

status is "complete" when the buyback has been confirmed via webhook, or empty string "" when still pending.

Response (Buyback Not Found):

{
"exists": false,
"message": "No buyback transaction found for this memo"
}

Error Responses:

  • 400: Missing memo parameter
  • 500: Database query failed

What it does: Checks if a buyback transaction has been completed for the given memo. Returns the buyback details if it exists, or indicates that no buyback was found.


Buyback Available - /api/buyback/availableโ€‹

Checks whether an NFT has an eligible buyback and returns the USDC amount that would be refunded. Lean read-only lookup โ€” no transaction is built. Eligibility matches the same rules as /api/buyback: the NFT must have been sent from the gacha within the last 72 hours and there must be no confirmed buyback for it yet.

Method: GET

Query Parameters:

  • nft (required): NFT mint address
  • wallet (optional): wallet public key; ignored (eligibility is NFT-scoped)

Example Request:

GET /api/buyback/available?nft=H9ZXYkudxn6qhyp5S25jm5SrA8Vnu8naSfvymm9TptLA

Response (Available):

{
"available": true,
"amount": 42500000,
"buybackExpiresAt": "2026-10-16T22:07:59.000Z"
}

amount is in USDC base units (6 decimals), already adjusted for the pack type's buyback percentage. It is clamped in dollars before scaling, to a floor of 0.01 USDC and a cap of 280,000 USDC โ€” the same bounds /api/buyback applies.

buybackExpiresAt is when the buyback window closes, as an ISO 8601 timestamp in UTC.

Response (Not Available):

{
"available": false
}

Error Responses:

  • 400: Missing nft parameter
  • 500: Database query failed

Bulk Buyback Available - /api/buyback/available/bulkโ€‹

Checks up to 100 NFTs in one request. Each entry is what /api/buyback/available returns for that NFT, plus nftAddress; an entry that could not be checked has error instead (see below).

Method: POST

Request Body:

{
"nftAddresses": ["nft_mint_address_1", "nft_mint_address_2"] // 1 to 100 entries; duplicates count toward the 100, and each distinct NFT gets one result
}

Response:

{
"results": [
{
"nftAddress": "nft_mint_address_1",
"available": true,
"amount": 42500000,
"buybackExpiresAt": "2026-10-16T22:07:59.000Z"
},
{
"nftAddress": "nft_mint_address_2",
"available": false
}
]
}

results has one entry per distinct NFT, in request order. amount and buybackExpiresAt mean the same as in /api/buyback/available. An entry with error instead of available could not be checked; check that NFT again.

Error Responses:

  • 400: Invalid JSON, or nftAddresses not an array of 1 to 100 non-empty strings of at most 44 characters

Errors for individual NFTs are reported in results, not as the response status.


Pack Status - /api/pack/statusโ€‹

Returns everything on record for a single memo across the three transaction tables: the pack purchase, the NFT send, and any buyback. Read-only lookup keyed entirely by the memo.

Method: GET

Query Parameters:

  • memo (required unless signature is given): The memo from the original pack purchase
  • signature (optional): the pack's payment transaction signature, for a pack whose memo you don't have (for example one paid by a Solana Pay QR code). Used only when memo is absent. A signature with no pack returns 200 with memo: null, signature, pack: null, send: null and buyback: [].

Example Request:

GET /api/pack/status?memo=953cc94e-fd51-4f5f-bbcc-5a35faf7df65
GET /api/pack/status?signature=5Nf9kZ...purchaseSignature

Response:

{
"memo": "953cc94e-fd51-4f5f-bbcc-5a35faf7df65",
"pack": {
"wallet": "GfFAJnHnSgP7C2FQZLz6ogpdTV6Y7259f83qFFm9wxKm",
"transaction_signature": "5Nf9kZ...purchaseSignature",
"created_at": "2025-05-26T17:30:00.000Z",
"status": "confirmed",
"webhook_received": true,
"refunded": null,
"refund_transaction_signature": null,
"turbo_mode": false,
"pack_type": "pokemon_50",
"token_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
},
"send": {
"from_wallet": "prize_wallet_public_key",
"to_wallet": "GfFAJnHnSgP7C2FQZLz6ogpdTV6Y7259f83qFFm9wxKm",
"nft_address": "H9ZXYkudxn6qhyp5S25jm5SrA8Vnu8naSfvymm9TptLA",
"transaction_signature": "3Dq2kH65vqEzpBKczyDLzNYS8sXmtS5GS9MYTwjVaPM4tqVxjtPGnQG4mKpSPa5iTzqomhFgo9nYs3grRNPp68Fh",
"created_at": "2025-05-26T17:31:00.000Z",
"status": "confirmed",
"webhook_sent": true,
"points": 0,
"insured_value": 50,
"prize_tier": 4,
"vrf_proof": "vrf_proof_string"
},
"buyback": [
{
"user_wallet": "GfFAJnHnSgP7C2FQZLz6ogpdTV6Y7259f83qFFm9wxKm",
"refund_amount": "42500000",
"created_at": "2025-05-26T17:32:33.588Z",
"webhook_confirmed": true,
"transaction_signature": "3Dq2kH65vqEzpBKczyDLzNYS8sXmtS5GS9MYTwjVaPM4tqVxjtPGnQG4mKpSPa5iTzqomhFgo9nYs3grRNPp68Fh",
"status": "confirmed",
"alt_recipient": null
}
]
}

Status values. All three status fields are two-state: "confirmed" or null. There is no "pending", "failed" or "refunded" value โ€” failure and refund are expressed by other fields.

Field"confirmed"null
pack.statusPayment verified; the pack can be opened. Terminal โ€” never reverts, including after a refund.Pack reserved but payment not yet seen on-chain. Stays null forever for an abandoned checkout. Always moves in lockstep with webhook_received, so either field answers "is it paid".
send.statusThe NFT transfer to the winner confirmed on-chain.Either the award row is still a placeholder (transaction_signature is null), or it is a turbo pack (transaction_signature is "turbomode"), which is never stamped even though it is fully delivered. Treat a send as delivered when status === "confirmed" or webhook_sent === true or transaction_signature === "turbomode".
buyback[].statusThe buyback settled: the card returned and the refund was paid.Quote issued / transaction submitted, not yet settled. A buyback whose transaction never landed is deleted rather than marked failed, so null on an old row means an unused quote. Treat as settled when status === "confirmed" or webhook_confirmed === true.

Do not confuse these with /api/buyback/check, which returns its own derived status of "complete" or "". That field does not appear here.

Field notes:

  • pack and send are the single row for that memo (or null if none exists yet).
  • buyback is an array โ€” a memo can have more than one buyback attempt โ€” ordered newest first; [] when there are none.
  • webhook_received (pack), webhook_sent (send), and webhook_confirmed (buyback) indicate the on-chain transaction was confirmed via webhook.
  • refunded is true when the pack was refunded, otherwise null; the refund's signature is in refund_transaction_signature.
  • refund_amount is returned as a string in USDC base units (6 decimals).
  • prize_tier values: 1 = Epic, 2 = Rare, 3 = Uncommon, 4 = Common.

Error Responses:

  • 400: Neither memo nor signature given
  • 500: Database query failed

Get Status - /api/statusโ€‹

Checks the current operational status of all gacha machines.

Method: GET

Request: No parameters required

Response:

{
"machineStatus": "running",
"legendaryStatus": "open",
"eliteStatus": "open",
"freePacksStatus": "closed",
"sportsStatus": "closed",
"gachas": [
{
"code": "pokemon_50",
"name": "Elite Pack",
"price": 50,
"status": "open",
"isOpen": true
}
]
}

machineStatus values:

  • "running" โ€” no emergency stop active
  • "stopped" โ€” emergency stop active, no purchases possible

status / individual machine values:

  • "open" โ€” machine is accepting purchases
  • "closed" โ€” machine is temporarily closed

gachas[].status and isOpen are each machine's own switch. While machineStatus is "stopped", no machine sells, even one whose status is "open".


Get Stock - /api/stockโ€‹

Returns current NFT inventory counts by rarity for each machine.

Method: GET

Response:

{
"elite": { "common": 34, "uncommon": 42, "rare": 86, "epic": 124 },
"legendary": { "common": 98, "uncommon": 85, "rare": 34, "epic": 24 },
"sports": { "common": 10, "uncommon": 5, "rare": 3, "epic": 1 },
"pokemon_50": { "common": 34, "uncommon": 42, "rare": 86, "epic": 124 },
"pokemon_250": { "common": 98, "uncommon": 85, "rare": 34, "epic": 24 }
}

The response includes both legacy named keys (elite, legendary, sports) and dynamic per-code keys for all machines.

Counts can be up to 10 seconds old.


Get Machines - /api/machinesโ€‹

Returns full configuration and live stock for every house machine (the machines Collector Crypt runs, such as pokemon_50). No API key needed. This is the recommended single call to build a machine-picker UI โ€” it includes odds, pricing, and current inventory all at once.

Machines you created or adopted are not listed here; read them from /api/v1/machines. Use /api/status to check whether each house machine is open.

Method: GET

Response:

{
"machines": [
{
"code": "pokemon_50",
"name": "Elite Pack",
"shortName": "Elite",
"mobile_name": null,
"image": "image_url",
"thumbnailUrl": "thumbnail_url",
"videoSrc": "video_url",
"videoHevc": "hevc_video_url",
"videoNobgWeb": "transparent_video_url_webm",
"videoNobgIos": "transparent_video_url_hevc_mp4",
"videoNobgAndroid": "transparent_video_url_android",
"imageNobg": "transparent_image_url",
"public": true,
"owner": "wallet_public_key",
"isPartner": false,
"adoptable": true,
"parentCode": null,
"menuOrder": 1,
"menuCategory": "Pokemon",
"price": 50,
"contains": 1,
"instantBuyback": 85,
"freeSpins": false,
"turboMode": false,
"fixedEv": false,
"pointsMultiplier": 1,
"lowThreshold": 50,
"odds": {
"epic": 0.01,
"rare": 0.04,
"uncommon": 0.15,
"common": 0.80
},
"tierRanges": {
"common": { "start": 0, "end": 25 },
"uncommon": { "start": 25, "end": 75 },
"rare": { "start": 75, "end": 200 },
"epic": { "start": 200, "end": 99999 }
},
"stock": {
"common": 34,
"uncommon": 42,
"rare": 86,
"epic": 124
},
"ev": 51.2
}
]
}

Fields:

FieldTypeMeaning
codestringThe machine code. Pass it as packType to /api/generatePack
name, shortNamestringDisplay name and short display name
mobile_namestring or nullDisplay name for mobile apps, when one is set. The key is snake_case
imagestringMachine image URL; "" when none is set
thumbnailUrl, videoSrc, videoHevcstringAlways set. A machine without an uploaded asset falls back to the bundled path (/<code>.png, /<code>.webm, /<code>.hevc.mp4)
videoNobgWeb, videoNobgIos, videoNobgAndroid, imageNobgstring or nullThe transparent-background (alpha) assets: one video encode per platform (Web = VP9-alpha webm for Chrome/Firefox, Ios = HEVC-alpha mp4 for Safari and iOS, Android = the Android app's encode) plus the alpha still image. There is no bundled fallback, so null means the machine has no asset for that platform. These replace the single videoNobg field
publicbooleanShown in the machine menu on gacha.collectorcrypt.com. A false machine is still listed here and still sells while it is open
ownerstring or nullThe wallet recorded as the machine's owner
isPartnerbooleanAlways false here: partner machines are not listed
adoptablebooleanA key with can_adopt can adopt this machine (see Adopting a machine)
parentCodestring or nullThe machine an adopted machine sells from. Always null here: adopted machines are not listed
menuOrdernumber or nullPosition in the site menu. The array is sorted by it, ascending with unset values last, then by price
menuCategorystring or nullThe site menu group, for example Pokemon, Sports or One Piece
pricenumberPack price in dollars
containsnumberCards per pack: 1 on every machine today, 0 if a machine leaves it unset
instantBuybacknumberBuyback payout as a percentage of the card's insured value
freeSpinsbooleanThe machine can be opened with free packs
turboModebooleanTurbo is offered on this machine
fixedEvbooleantrue for a Fixed EV machine, false for Dynamic EV (see Fixed EV vs Dynamic EV)
pointsMultipliernumberMultiplier on the points a pack earns. Packs bought with an API key earn no points
lowThresholdnumberCommon-tier stock below which a non-turbo pack is refused with Machine is empty. Every pack is also refused while uncommon, rare or epic is below 5, and a turbo pack while common is at 0 (Machine is low). 50 when the machine sets none
oddsobjectPer-tier chance of a pack, as fractions that sum to 1. On a Fixed EV machine these are the published odds: uncommon and rare are re-solved for each pack, and the odds a pack used are shown at /verify-selection/<memo>
tierRangesobjectEach tier's insured-value range in dollars: start inclusive, end exclusive
stockobjectActive cards per tier. Can be up to 20 seconds old
evnumber or nullThe machine's current rarity-weighted expected insured value: each tier's average insured value weighted by its odds, in dollars and unrounded. It is null, never 0, whenever it is unavailable (for example before it is first calculated), so guard before doing arithmetic on it

Fields are never removed or renamed; new ones may be added.


Get Machine - /api/machines/<code>โ€‹

Returns one house machine: the same object as its entry in the machines array of /api/machines, with the same fields and the same freshness. No API key needed.

Method: GET

Example Request:

GET /api/machines/pokemon_50

Response: the machine object itself, not wrapped in machines.

{
"code": "pokemon_50",
"name": "Elite Pack",
"price": 50,
"odds": { "epic": 0.01, "rare": 0.04, "uncommon": 0.15, "common": 0.80 },
"stock": { "common": 34, "uncommon": 42, "rare": 86, "epic": 124 },
"ev": 51.2
}

(Shortened here. Every field listed under /api/machines is present.)

Errors:

  • 404 {"error": "Machine not found", "code": "NOT_FOUND"}: no house machine has that code. Codes are case-sensitive. Machines you created or adopted are not served here; read them from /api/v1/machines.

Get NFTs - /api/getNftsโ€‹

Retrieves NFTs available in the gacha machine filtered by code and optionally by rarity.

Method: GET

Query Parameters:

  • code (optional): The pack/collection code (e.g., "pokemon_50"). Defaults to pokemon_50. For an adopted machine pass its own code; it lists the pool that machine sells from.
  • rarity (optional): Filter by rarity tier - "common", "uncommon", "rare", or "epic". Matched case-insensitively; any other spelling (e.g. Common) gets a 307 to the lowercase URL.
  • limit (optional): page size. Send limit=1 for a one-card preview, leave it out for a page of 40, or send limit=100 to walk a whole pool. Don't use other values: a few remain for existing integrations, the rest get a 307 to a supported size, and 61โ€“99 are rejected with 403.
  • cursor (optional): opaque position token. Omit it for the first page, then pass back the nextCursor from the previous response.

Results are ordered by insured value descending, then mint address ascending.

Redirects: a request that is not in canonical form (parameters out of order, a different spelling of the same value, an empty rarity, an unreadable cursor) gets a 307 to the canonical URL, which is served from cache. Make sure your HTTP client follows redirects.

Example Requests:

GET /api/getNfts?code=pokemon_50
GET /api/getNfts?code=pokemon_50&rarity=epic

# first page
GET /api/getNfts?code=pokemon_50&limit=100
# every page after it โ€” feed back nextCursor
GET /api/getNfts?code=pokemon_50&limit=100&cursor=630_3ymjGXyc3k2RtjmTMxNWaMNNPSAU5vst2LiFamYUAmKj

Response:

{
"nfts": [
{
"nft_address": "nft_mint_address",
"name": "Card Name",
"description": "Card Description",
"rarity": "epic",
"attributes": [...],
"image": "image_url",
"insured_value": 250
}
],
"page": 1,
"limit": 100,
"hasMore": true,
"nextCursor": "630_3ymjGXyc3k2RtjmTMxNWaMNNPSAU5vst2LiFamYUAmKj"
}

limit is the page size actually used. page is left from the removed offset paging: it echoes a page parameter, 1 when none is sent. Ignore it.

Walking a whole pool: request the first page, then keep passing nextCursor back as cursor until hasMore is false. Use limit=100, and keep code, rarity and limit the same across the walk.

  • nextCursor is an opaque token โ€” pass it back unchanged. Do not parse or construct it yourself; its format is not part of the contract and may change.
  • hasMore is true when another page is available. When it is false, nextCursor is null and you have reached the end.
  • The cursor resumes exactly after the last row you were given, so pages never overlap or skip even while inventory changes underneath you, and every page costs the same no matter how deep you go.

Error Responses:

  • 404: {"error": "Unknown machine", "code": "<code>"} when no machine has that code
  • 410: page greater than 1 without a cursor. Offset pages were removed; walk the pool with cursor.
  • 500: Database query failed

Submit Transaction - /api/submitTransactionโ€‹

Submits a signed transaction to the Solana blockchain.

Method: POST

Request Body:

{
"signedTransaction": "base64_encoded_signed_transaction"
}

Response (Success):

{
"success": true,
"signature": "transaction_signature_hash",
"confirmationStatus": "confirmed"
}

confirmationStatus is one of "confirmed", "finalized", or "submitted" (the last one means the transaction was sent but not yet confirmed within the valid block height window).

Example Request:

curl -X POST "/api/submitTransaction" \
-H "Content-Type: application/json" \
-H "x-api-key: API_KEY" \
-d '{
"signedTransaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQABBqF55bPp..."
}'

Error Responses:

  • 400: Missing or invalid signed transaction, or a pack payment that does not match its pack (error: "Transaction failed payment verification" with a reason)
  • 400: The network rejected the transaction:
    {
    "success": false,
    "error": "Transaction expired, please refresh and try again",
    "code": "BLOCKHASH_EXPIRED",
    "signature": "transaction_signature_hash"
    }
    code is BLOCKHASH_EXPIRED (request a fresh transaction and sign it again), or EXECUTION_FAILED or PREFLIGHT_FAILED (the network refused it, for example for too little balance; error gives the reason).
  • 403: Transaction not signed by the gacha wallet
  • 500: Transaction submission failed or blockchain error

What it does: Takes a fully signed transaction (from /api/generatePack or /api/buyback after user signing) and submits it to the Solana blockchain. Returns the transaction signature for tracking.


Generate Gift - /api/generateGiftโ€‹

Creates a transaction to gift packs to another wallet. The sender pays for the packs; after submitting the signed transaction, the receiver will have gifted packs available to open on gacha.collectorcrypt.com.

Method: POST

Request Body:

{
"sender": "HWPRgtDGpBm8mByTGS57BWCsijMo53qPPSbskWDukfTc",
"receiver": "daxsSgG4iPvhxWr2jrY76HKtRSjWjQLFveKHdmZKJFc",
"packType": "pokemon_50",
"count": 1, // optional; must be an integer between 1 and 20, defaults to 1
"token": "USDC" // optional, defaults to USDC; same as /api/generatePack
}

Response:

{
"giftId": 2,
"memo": "cc-86646f0c-2a61-4a0a-89af-495d266684c3",
"transaction": "base64_encoded_transaction",
"totalCost": 50,
"count": 1,
"packType": "pokemon_50"
}

Note on the memo: The returned memo is prefixed with your API-key slug, or with cc- when no x-api-key is sent (e.g. cc-<uuid>) โ€” it is not prefixed gift-. The gift marker is only appended to the on-chain memo (as a :gift suffix) and never appears in the memo field returned by this endpoint.

Example Request:

curl -X POST "https://gacha.collectorcrypt.com/api/generateGift" \
-H "Content-Type: application/json" \
-d '{
"sender":"HWPRgtDGpBm8mByTGS57BWCsijMo53qPPSbskWDukfTc",
"receiver":"daxsSgG4iPvhxWr2jrY76HKtRSjWjQLFveKHdmZKJFc",
"packType":"pokemon_50",
"count":1
}'

What it does: Returns a transaction. Sign it, then POST it to /api/submitTransaction. Once confirmed, the receiver will have gifted packs to open on gacha.collectorcrypt.com.


Get Gifted - /api/getGiftedโ€‹

Fetches gift history for a wallet โ€” both sent and received gift packs, totals grouped by pack type, and a per-pack opening history for received gifts.

Method: GET

Query Parameters:

  • wallet (required): wallet public key

Example Request:

GET /api/getGifted?wallet=HWPRgtDGpBm8mByTGS57BWCsijMo53qPPSbskWDukfTc

Response:

{
"wallet": "HWPRgtDGpBm8mByTGS57BWCsijMo53qPPSbskWDukfTc",
"sent": [
{
"id": 1,
"memo": "cc-86646f0c-2a61-4a0a-89af-495d266684c3",
"sender": "wallet_public_key",
"receiver": "wallet_public_key",
"pack_type": "pokemon_50",
"count": 1,
"cost": 50,
"webhook_confirmed": true,
"status": "confirmed",
"transaction_signature": "tx_signature",
"created_at": "2025-01-01T00:00:00.000Z"
}
],
"received": [ /* same shape as sent */ ],
"totals": {
"sent": [
{ "pack_type": "pokemon_50", "count": 5, "cost": 250 }
],
"received": [
{ "pack_type": "pokemon_50", "count": 3, "cost": 150 }
]
},
"perpack": [
{
"pack_opened_id": 123,
"purchase_type": "gift",
"purchase_id": 1,
"wallet": "receiver_wallet",
"pack_type": "pokemon_50",
"opened_date": "2025-01-02T00:00:00.000Z",
"purchase_signature": "gift_tx_signature",
"send_nft_txn": "send_nft_signature",
"memo": "cc-uuid",
"insured_value": 50,
"pack_quantity": 1
}
]
}

The perpack array tracks each individual gift pack opening for the receiver wallet.


Purchased Packs Summary - /api/purchasedPacksโ€‹

Returns pack counts for a wallet (purchased vs gifted, used vs unused) grouped by packType. The response contains one entry per configured pack type โ€” derived dynamically from the active machines โ€” so the keys returned depend on which machines exist, not only the two shown below.

Method: GET

Query Parameters:

  • wallet (required): wallet public key

Example Request:

GET /api/purchasedPacks?wallet=daxsSgG4iPvhxWr2jrY76HKtRSjWjQLFveKHdmZKJFc

Response:

{
"pokemon_50": {
"purchased": 0,
"gifted": 2,
"used_purchased": 0,
"used_gifted": 1
},
"pokemon_250": {
"purchased": 0,
"gifted": 0,
"used_purchased": 0,
"used_gifted": 0
}
}

Generate Purchased Pack Challenge - /api/generatePurchasedPackโ€‹

Generates a message-to-sign challenge for opening a purchased/gifted pack.

Gift opening flowโ€‹

  1. Call /api/generatePurchasedPack to get a nonce + messageToSign.
  2. Have the user sign messageToSign with their wallet.
  3. Call /api/usePurchasedPack:
  • non-ledger: { signedMessage, signature, publicKey, nonce, packType }
  • ledger: { ledger: true, transactionSignature, publicKey, nonce, packType, turbo } to receive a memo.
  1. Call /api/openPack with the memo to send the NFT.

Reference UI (dev)โ€‹

Method: POST

Request Body:

{
"publicKey": "daxsSgG4iPvhxWr2jrY76HKtRSjWjQLFveKHdmZKJFc",
"packType": "pokemon_50",
"ledger": true
}
  • ledger (optional, default: false): when true, the server returns a Ledger-compatible challenge flow.

Response:

{
"success": true,
"nonce": "23a8bb98-d975-454f-a410-28e072247afa",
"expiry": "2026-02-25T20:48:42.317Z",
"messageToSign": "Open my purchased pokemon_50 pack!\n\nNonce:23a8bb98-d975-454f-a410-28e072247afa",
"ledger": true
}

Use Purchased Pack - /api/usePurchasedPackโ€‹

Consumes a purchased/gifted pack after the wallet signs the challenge message. Returns a memo you can open like normal (via /api/openPack).

Method: POST

Request Body:

{
"ledger": true,
"nonce": "7b24cb5b-f3f6-4f6d-b039-6d1bc05b6060",
"packType": "pokemon_50",
"publicKey": "HWPRgtDGpBm8mByTGS57BWCsijMo53qPPSbskWDukfTc",
"transactionSignature": "signed_transaction",
"turbo": true
}

Request Body (non-ledger):

{
"signedMessage": "Open my purchased pokemon_50 pack!\n\nNonce:89c3e1b3-9d50-4cdd-95e6-444ef3fd68e4",
"signature": "base58_signature",
"publicKey": "daxsSgG4iPvhxWr2jrY76HKtRSjWjQLFveKHdmZKJFc",
"turbo": false,
"packType": "pokemon_50",
"nonce": "89c3e1b3-9d50-4cdd-95e6-444ef3fd68e4"
}

Response:

{
"success": true,
"memo": "cc-83f67f2e-7b53-45fd-9d81-ab4f8243475c",
"packsRemaining": 0
}

Winners on EVM chainsโ€‹

The winners endpoints below list wins from every chain, Solana and EVM, together. Each row carries three chain fields, all null on a Solana win:

  • chain_id: the EVM chain the pack was bought on (see /api/evm/chains).
  • evm_contract_address and evm_token_id: the ERC-721 the winner received. evm_token_id is null until the token is minted.

On an EVM win, winner is the buyer's 0x address and nft_address is the Solana card that backs the ERC-721. The live winners feed carries EVM wins too, with its own rules for these fields; see Live Winners Token.


Get Recent Winners - /api/getRecentWinnersโ€‹

Returns the most recent winners for a single machine, newest first (up to 5).

Method: GET

Query Parameters:

  • packType (optional): The machine/pack code (e.g. pokemon_50, pokemon_250). Defaults to 50.

packType is the only parameter. A request with any other parameter, or more than one, gets a 307 to ?packType=<value>, so make sure your HTTP client follows redirects.

Example Request:

GET /api/getRecentWinners?packType=pokemon_50

Response:

{
"success": true,
"data": [
{
"winner": "wallet_address",
"prize_tier": 1,
"nft": {
"content": { "metadata": { "name": "Card Name", "attributes": [...] } },
"image": "https://..."
},
"timestamp": "2024-01-01T12:00:00Z",
"insuredValue": 250,
"chain_id": null,
"evm_contract_address": null,
"evm_token_id": null
}
]
}

The best available image URL is merged onto the nft object as image. prize_tier values: 1 = Epic, 2 = Rare, 3 = Uncommon, 4 = Common. The chain fields are explained in Winners on EVM chains.

Error Responses:

  • 200 with data: [] when that pack type has no winners yet โ€” there is no 404 for an empty or unknown packType.
  • 500: Database query failed

Get All Winners - /api/getAllWinnersโ€‹

Returns winners newest first, optionally filtered by memo slug, pack type, rarity and time. Pass cursor to page through the full history with any combination of these filters.

Method: GET

Query Parameters:

  • timestamp (optional): ISO 8601 timestamp to get winners after this time. If omitted, returns the latest winners with no cutoff.
  • slug (optional): Filter by memo prefix (e.g., "me")
  • epic (optional): Set to "true" to get only epic/legendary wins
  • packType (optional): Filter by pack type (e.g., "pokemon_50", "pokemon_250")
  • count (optional): Number of results per page (default: 10, max: 200)
  • cursor (optional): The nextCursor returned by the previous page. Omit it to fetch the first (most recent) page.
  • wallet (optional): a Solana address or an EVM 0x address (any case). Returns that wallet's count most recent wins on its own chain. The other filters and cursor are ignored, and there is no nextCursor or hasMore. 400 when the address is invalid.
  • perTier (optional, 1โ€“25): returns the perTier most recent wins of each rarity together with the 10 most recent wins of each machine, newest first. The other filters, count and cursor are ignored, and there is no nextCursor or hasMore. wallet wins over perTier when both are sent.

With wallet or perTier, each nft is trimmed to content.metadata.name, content.metadata.description, content.metadata.attributes (only Grading Company, GradeNum and Insured Value) and the image as content.files[0].cc_cdn.

Example Request:

GET /api/getAllWinners?timestamp=2024-01-01T00:00:00Z&slug=me&epic=false&packType=pokemon_50&count=20

Example Request (next page):

GET /api/getAllWinners?packType=pokemon_50&count=50&cursor=MjAyNC0wMS0wMVQxMjowMDowMC4wMDAwMDBafDEyMzQ1

Response:

{
"success": true,
"data": [
{
"winner": "wallet_address",
"nft_address": "nft_mint_address",
"nft": {
"content": {
"metadata": {
"name": "Card Name",
"attributes": [...]
}
}
},
"insuredValue": 250,
"created_at": "2024-01-01T12:00:00Z",
"memo_slug": "me",
"pack_type": "pokemon_50",
"prize_tier": 1,
"chain_id": null,
"evm_contract_address": null,
"evm_token_id": null
}
],
"nextCursor": "MjAyNC0wMS0wMVQxMjowMDowMC4wMDAwMDBafDEyMzQ1",
"hasMore": true
}

Pagination:

  • nextCursor is an opaque token โ€” pass it back as the cursor parameter, with the same filters, to fetch the next page. Do not parse or construct it yourself.
  • hasMore is true when another page is available. When hasMore is false, nextCursor is null and you've reached the end.
  • Results are ordered most recent first and remain stable as new winners arrive, so you won't skip or double-count rows while paginating.

prize_tier values: 1 = Epic, 2 = Rare, 3 = Uncommon, 4 = Common. The chain fields are explained in Winners on EVM chains.

Error Responses:

  • 400: Invalid timestamp, invalid cursor or invalid wallet
  • 500: Database query failed

What it does: Returns NFT winners optionally filtered by timestamp, memo prefix (slug), rarity (epic), and pack type, most recent first. cursor pages through every matching winner.


Get Winners (Paginated) - /api/getWinnersโ€‹

Cursor-paginates through all winners for a single memo slug, newest first, and every page is fast regardless of how deep you go. /api/getAllWinners pages the same way and can also filter by pack type, rarity and time.

Each winner has the same shape as /api/getAllWinners; the response just adds the pagination fields nextCursor and hasMore.

Method: GET

Query Parameters:

  • slug (required): The memo slug to fetch winners for (your API key's slug).
  • cursor (optional): The nextCursor returned by the previous page. Omit it to fetch the first (most recent) page.
  • count (optional): Page size (default: 50, max: 200).

Example Request (first page):

GET /api/getWinners?slug=me&count=50

Example Request (next page):

GET /api/getWinners?slug=me&count=50&cursor=MjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDBafDEyMzQ1

Response:

{
"success": true,
"data": [
{
"winner": "wallet_address",
"nft_address": "nft_mint_address",
"nft": {
"content": {
"metadata": {
"name": "Card Name",
"attributes": [...]
}
}
},
"insuredValue": 250,
"created_at": "2024-01-01T12:00:00Z",
"memo_slug": "me",
"pack_type": "pokemon_50",
"prize_tier": 1,
"chain_id": null,
"evm_contract_address": null,
"evm_token_id": null
}
],
"nextCursor": "MjAyNC0wMS0wMVQxMjowMDowMC4wMDAwMDBafDEyMzQ1",
"hasMore": true
}

Pagination:

  • nextCursor is an opaque token โ€” pass it back as the cursor parameter to fetch the next page. Do not parse or construct it yourself.
  • hasMore is true when another page is available. When hasMore is false, nextCursor is null and you've reached the end.
  • Results are ordered most recent first and remain stable as new winners arrive, so you won't skip or double-count rows while paginating.

prize_tier values: 1 = Epic, 2 = Rare, 3 = Uncommon, 4 = Common. The chain fields are explained in Winners on EVM chains.

Error Responses:

  • 400: Missing slug or invalid cursor
  • 500: Database query failed

Live Winners Token - /api/ably/tokenโ€‹

Issues a short-lived Ably token so you can subscribe to live wins in realtime โ€” the same feed that powers the Recent Winners section on the gacha site. Use this instead of polling /api/getAllWinners when you want wins to appear in your UI the moment they happen.

Any valid API key can subscribe to all winner channels; filter by gachaCode (or memo) on your end to show only the machines you care about.

Method: GET

Headers:

  • x-api-key (required): your API key.

Example Request:

curl "https://gacha.collectorcrypt.com/api/ably/token" \
-H "x-api-key: API_KEY"

Response: an Ably TokenRequest object. You don't parse this yourself โ€” hand it straight to the Ably client (see below). It is scoped to subscribe-only on the channels below and expires after 1 hour; the Ably client auto-renews by re-calling this endpoint.

Usage (browser / Node):

import * as Ably from "ably";

const ably = new Ably.Realtime({
authUrl: "https://gacha.collectorcrypt.com/api/ably/token",
authHeaders: { "x-api-key": "API_KEY" },
});

// One channel per pack type, e.g. recent-winners-pokemon_50
ably.channels.get("recent-winners-pokemon_50")
.subscribe("new-winner", (msg) => {
console.log(msg.data); // see payload below
});

The channel name is recent-winners-{packType} and the event name is new-winner. Each message's data is:

{
"winner": "wallet_address",
"prizeWallet": "wallet_address",
"nft": {
"address": "nft_mint_address",
"name": "Card Name",
"image": "https://...",
"certid": "1234567",
"gradingCompany": "PSA",
"grade": "10"
},
"timestamp": "2024-01-01T12:00:00Z",
"insuredValue": 250,
"weightedInsuredValue": 51.2,
"gachaCode": "pokemon_50",
"prizeTier": 1,
"memo": "me-abc123"
}

prizeTier values: 1 = Epic, 2 = Rare, 3 = Uncommon, 4 = Common.

A win on an EVM chain also carries chain_id, evm_contract_address and evm_token_id. Its winner is a 0x address, and nft.address is the Solana card that backs the ERC-721 (see Winners on EVM chains). Solana wins don't include those three keys.

The live message is sent before the token is minted, so its evm_token_id is always null. Read the token id later from /api/getWinners or /api/evm/pack/status, using the message's memo.

memo is the unique pack identifier returned by /api/generatePack (or /api/evm/generatePack) โ€” use its slug prefix (e.g. me) to filter to your own machines, and the full value to attribute a win to the specific player/pack you created.

Epic wins: the epic-wins channel carries every Epic win (prizeTier: 1) across all pack types, with the same new-winner event and payload. Subscribe to it instead of every winner channel when you only show Epics.

Pack payment confirmations: the pack-paid-memo:{memo} channel tells you when a pack's payment is confirmed, so you can call /api/openPack once instead of polling it. The event name is update and its data is:

{
"memo": "slug-uuid-string",
"signature": "transaction_signature",
"status": "confirmed"
}
const ch = ably.channels.get(`pack-paid-memo:${memo}`, { params: { rewind: "1" } });
ch.subscribe("update", async (msg) => {
if (msg.data.status !== "confirmed") return;
await ch.detach();
ably.channels.release(`pack-paid-memo:${memo}`);
// call /api/openPack with memo
});
  • Attach before you send the payment transaction. rewind: "1" also delivers a message sent just before you attached.
  • Not every pack gets this message. If /api/submitTransaction returned confirmationStatus "confirmed" or "finalized", call /api/openPack right away. Otherwise, if nothing arrives within about 15 seconds, fall back to polling /api/openPack.
  • Detach and release each pack's channel once the pack is open.

Error Responses:

  • This endpoint does not 401. Without a recognised x-api-key โ€” or with a key whose slug is empty โ€” it returns a token scoped to the first-party channel set instead of your partner scope, so a typo fails silently. If the channels you expect are missing, check that your key is live.

What it does: Mints a scoped Ably token tied to your key. Subscribe to the recent-winners-{packType} channels (or epic-wins) and react to new-winner events to render wins live, and to pack-paid-memo:{memo} to open a pack as soon as its payment is confirmed.

Flow Summaryโ€‹

  1. Call /api/generatePack to create a purchase transaction
  2. Sign the transaction with your wallet
  3. Submit signed transaction via /api/submitTransaction
  4. Wait for confirmation
  5. Call /api/openPack with the memo to receive the NFT
  6. (Optional) Call /api/buyback within 72 hours to sell the NFT back for USDC (/api/buyback/bulk for several NFTs at once)
  7. Use /api/getAllWinners to display recent winners in your UI

Partner Operationsโ€‹

Everything above is about playing a machine. This section is about operating one: seeing your machines' live state, and โ€” if your key is enabled for it โ€” building your own or attaching a fee to one of ours.

Three independent capabilities are set per API key. All are off by default; ask us to enable them.

CapabilityWhat it allows
can_adoptAttach a per-pack fee to a CollectorCrypt machine (see Adopting a machine)
can_build_machinesCreate and edit your own machines on our shared inventory
can_edit_hashlistsCurate which cards are active in machines you operate

Fixed EV vs Dynamic EVโ€‹

Every machine is one of two kinds, and it changes what "odds" means:

  • Fixed EV โ€” the machine re-solves its odds on every pack so it delivers exactly its target expected value. It moves probability between the uncommon and rare tiers only; the advertised common (big-win) and epic (jackpot) chances never move. If the pool cannot reach the target, the machine refuses the sale rather than paying out the wrong value โ€” you'll see 503/500 Machine is off balance. The odds actually used are committed per pack before the roll and are provable at /verify-selection/<memo>.
  • Dynamic EV โ€” the published odds are fixed and the expected value drifts inside a band. A background job steers it by activating and deactivating cards.

A machine's floor is the cheapest EV its odds can reach on its current cards. It is set mostly by the common tier, because that is where most of the probability mass sits.

GET /api/v1/machinesโ€‹

Only the machines your key owns (ones you created or adopted), authenticated by x-api-key. House machines such as pokemon_50 are not listed, even though your key can sell them: read those from /api/machines. A key that owns no machines gets {"machines": []}.

FieldMeaning
codeThe packType to pass to /api/generatePack
nameDisplay name
enabledMachine toggled on
price, instantBuyback, tierRangesPack price in dollars, buyback as a percentage of insured value, and each tier's insured-value range
partnerFeeYour per-pack fee, if any
targetEvThe EV this machine aims to deliver
targetEvMin, targetEvMaxThe band the EV is kept inside; null when not set
evThe EV a pack bought now delivers
oddsPer-tier odds of a pack bought now, as fractions that sum to 1 (same shape as odds on /api/machines). null when the machine has no cards or a Fixed EV machine cannot reach its target
evLow, evHighThe cheapest and richest EV the odds can reach on current stock
reachableWhether targetEv sits inside [evLow, evHigh]
stockActive owned cards per tier
lowThresholdThe common-tier count below which the machine is low
lowCommon is under lowThreshold, or uncommon, rare or epic is under 5
sellsA pack bought now would be accepted
blockedCodenull when sells is true; otherwise why not

EV fields are in dollars, unrounded: round them for display. Production and devnet return the same fields. Fields are never removed or renamed; new ones may be added.

When sells is false, blockedCode is one of:

blockedCodeMeaning
MACHINE_OFFThe machine, or the machine it belongs to, is off
OFF_BALANCEThe EV is above its ceiling, or a Fixed EV machine cannot reach its target
MACHINE_LOWlow is true
INTERNALServer error; contact us

sells does not cover per-wallet limits or the brief "too many packs open" pause. A turbo pack can still sell while only the common tier is under lowThreshold. If sells is false, check reachable first: a Fixed EV machine whose target is outside [evLow, evHigh] needs its target moved or its inventory changed.

An Invoiced API key gets that API's own checks instead.

GET /api/v1/stockโ€‹

Per-tier active card counts for each machine your key owns (the same set as /api/v1/machines), plus the low-stock flag. Cheaper than /api/v1/machines when you only need availability. House machine stock is on /api/stock.

{
"my_machine_50": {
"common": 120,
"uncommon": 40,
"rare": 12,
"epic": 6,
"lowThreshold": 50,
"low": false
}
}

One key per machine code. lowThreshold and low mean the same as on /api/v1/machines. A key that owns no machines gets {}; a missing or invalid key gets 401 {"error": "Missing or invalid API key", "code": "UNAUTHORIZED"}.

Adopting a machineโ€‹

With can_adopt, you can take one of our machines and attach a per-pack fee. You sell the same cards from the same pool at the same price; your fee comes out of the expected value, so your players receive exactly your fee less than ours. Nothing else about the machine changes.

your machine's EV = our machine's EV - your fee

Our machine's EV is the targetEv we set on it, shown per machine on the adoption screen. If we later change it, your machine's EV follows within a minute; your fee does not change.

The fee is capped two ways, and the smaller wins:

  1. Policy โ€” at most 10% of the pack price.
  2. Physical โ€” the EV left over must still be at or above the pool's floor (evLow). A fee that pushes the EV below what the cards can pay out would never sell, so it is rejected at setup.

So on a $50 pack with a $51 EV the policy cap is $5, but if that pool cannot pay out less than $47 the physical cap binds first at 51 โˆ’ 47 = $4.00. The adoption screen shows the number you can actually set.

Adopting creates a new machine code scoped to your key. It is private, starts disabled, and is listed in /api/v1/machines like any other. Its price and fee are locked at creation so accrued fees can never move. It has no inventory of its own โ€” we stock the underlying pool.

How fees accrue and pay outโ€‹

A fee is earned when the pack completes, i.e. the card was actually awarded. A completed pack is non-refundable, so an earned fee cannot be clawed back โ€” there is no maturity window.

Split fee. When split fee is on for your account, half of each pack's fee is earned when the pack completes and the other half only when that pack's card is sold back to us. If the player keeps the card, the second half is not earned. On a $10 fee: $5 at completion, plus $5 if the card is bought back. New accounts start with split fee on. The setting that applies is the one in force when the pack was sold, so changing it never moves fees already earned. Your Earnings page shows both halves.

Fees are tracked in ยตUSDC (1 USDC = 1,000,000) and paid to the treasury wallet on your account. Solana and EVM packs both accrue; payouts settle in Solana USDC either way. Payouts are released by a CollectorCrypt admin, not automatically.