Skip to main content

Gacha Invoiced API

The Invoiced API lets a partner with its own accounts, payments and storefront sell CollectorCrypt gacha packs to its users. You issue a pack, your user opens it, and the card they win is held for them by CollectorCrypt. Your user can sell it back inside the buyback window, have it shipped at any time (Invoiced Shipping), or keep it. Your users pay you, not the chain: once a month you receive an invoice and you pay it in USDC (Payments).

What you must know​

  1. Open right after the sale. A pack must be opened within 2 hours of being issued.
  2. The roll is fixed once the pack is opened. A retry gives the same result. Signing the seed yourself is optional; see Seed.
  3. playerRef and clientRef are your own opaque ids. Never put a name, email, phone number or handle in them.
  4. A card can ship as soon as it is won. Buybacks close 72 hours after the award (720 hours on Development), unless your agreement sets a different window. Each card's buybackExpiresAt is its deadline. A card in a shipment cannot be sold back; cancelling an unpaid shipment frees it. About a day after its buyback closes, a kept card moves into vault custody.
  5. List reads can lag by a few seconds. GET /packs/{memo} is always current.
  6. A draft invoice is provisional. Only an issued invoice is a bill. A month is issued once its last buyback window has closed.
  7. Unpaid cards are capped by your credit limit, which starts at $50,000. Paying your invoice restores it. See Credit limit and Payments.

Base URL and authentication​

EnvironmentBase URL
Productionhttps://gacha.collectorcrypt.com/api/v1
Developmenthttps://dev-gacha.collectorcrypt.com/api/v1

CollectorCrypt issues your API key for each environment. Send it on every request, as x-api-key: <key> or Authorization: Bearer <key>. A missing, invalid or revoked key gets 401 UNAUTHORIZED. Another partner's packs, cards and users return 404. Keys do not expire; rotate or revoke them in the partner panel.

Lists take limit (default 50, max 200) and cursor: pass nextCursor back as cursor until it is null.

Machines​

GET /machines lists the machines your key can sell, with the fields in the /api/v1/machines table. Use a machine's code as packType.

  • sells says whether POST /packs would accept a pack now. When it is false, blockedCode is the code POST /packs would return: RAIL_PAUSED, OUT_OF_CREDITS, MACHINE_OFF, OFF_BALANCE, MACHINE_LOW, MACHINE_NOT_ELIGIBLE, UNKNOWN_MACHINE or INTERNAL.
  • low: true stops sales: POST /packs returns 503 MACHINE_LOW.
  • partnerFee is always 0. A fee from your deal is on your invoices and in the ledger.

Packs​

POST /packs — issue​

{ "packType": "pokemon_50", "playerRef": "user-8431", "clientRef": "order-77120" }
  • playerRef is required, ^[A-Za-z0-9_-]{1,128}$.
  • clientRef is optional, ^[A-Za-z0-9_.:-]{1,128}$. The same clientRef returns the same pack with "replay": true.
{
"replay": false,
"memo": "abcde-5f3c2b1a-…",
"packType": "pokemon_50",
"playerRef": "user-8431",
"clientRef": "order-77120",
"price": 50,
"currency": "USD",
"buybackPct": 90,
"odds": { "epic": 0.03, "rare": 0.07, "uncommon": 0.2, "common": 0.7 },
"poolVersion": "1289",
"expiresAt": "2026-10-01T14:02:11.000Z"
}

price is what you are invoiced for the pack.

POST /packs/{memo}/open​

Send an empty body, or { "clientSeed": "…" } if you sign your own seeds.

{
"success": true,
"replay": false,
"memo": "abcde-5f3c2b1a-…",
"roll": 41203377,
"rarity": "rare",
"rarityLabel": "Rare",
"prizeTier": 2,
"nftAddress": "7xKX…",
"cardName": "Charizard ex",
"nft": { "…": "card metadata" },
"insuredValue": 120,
"buybackCredit": 108,
"buybackExpiresAt": "2026-10-04T12:02:14.000Z"
}

Opening again returns the stored award with "replay": true. 202 PROCESSING means an earlier open is still finishing: poll GET /packs/{memo}. buybackCredit is fixed when the card is won.

GET /packs/{memo}​

The pack, its award and where the card is now. state is one of issued, expired, processing, held (not yet in the vault; the buyback may be open), in_vault (buyback closed), shipped, bought_back. held and in_vault cards can ship. shipmentId is the shipment the card is in, set when that shipment is created. It is null again if the shipment is cancelled, expires or fails before payment. After payment it never changes.

{
"memo": "abcde-…", "packType": "pokemon_50", "playerRef": "user-8431", "clientRef": "order-77120",
"price": 50, "buybackPct": 90, "createdAt": "…", "expiresAt": "…", "seeded": true, "state": "held",
"award": { "roll": 41203377, "rarity": "rare", "prizeTier": 2, "nftAddress": "7xKX…", "cardName": "…",
"nft": { }, "insuredValue": 120, "buybackCredit": 108, "awardedAt": "…" },
"buybackOpen": true, "buybackExpiresAt": "…", "buyback": null, "releasedAt": null, "shipmentId": null
}

buyback becomes { "creditAmount": 108, "boughtBackAt": "…" } once the card is sold back.

POST /packs/{memo}/buyback and GET /packs/{memo}/buyback​

POST sells the card back for its buybackCredit, netted on your invoice. Repeating it returns the same result with "replay": true. A card in a shipment cannot be sold back: 409 ALREADY_SHIPPING. Cancel an unpaid shipment to free it.

{ "success": true, "replay": false, "memo": "abcde-…", "creditAmount": 108, "ownershipSeq": "918273" }

GET checks eligibility without changing anything:

{ "memo": "abcde-…", "eligible": true, "creditAmount": 108, "buybackExpiresAt": "…" }

When eligible is false, reason is PROCESSING, ALREADY_BOUGHT_BACK, BUYBACK_WINDOW_CLOSED or ALREADY_SHIPPING.

Bulk: many packs in one call​

Bulk calls do what the single calls do, for many packs at once.

Issue up to 20: POST /packs with count

{ "packType": "pokemon_50", "playerRef": "user-8431", "clientRef": "order-77120", "count": 5 }
{
"packs": [
{ "replay": false, "memo": "abcde-5f3c2b1a-…", "clientRef": "order-77120:1", "packType": "pokemon_50", "price": 50, "…": "…" },
{ "replay": false, "memo": "abcde-9d01e4c7-…", "clientRef": "order-77120:2", "packType": "pokemon_50", "price": 50, "…": "…" }
]
}
  • count is a whole number from 1 to 20. Each item in packs is the single issue response.
  • All or nothing: if the packs cannot be sold, you get the same error as for one pack and none is issued.
  • One playerRef per call.
  • With clientRef, pack n gets the clientRef <clientRef>:n, so here clientRef can be at most 125 characters. The same clientRef and count again returns the same packs with "replay": true; a different count returns 409 CLIENT_REF_CONFLICT.
  • Without count, POST /packs issues one pack, as above.

Open up to 20: POST /packs/open

{ "packs": [ { "memo": "abcde-5f3c2b1a-…" }, { "memo": "abcde-9d01e4c7-…", "clientSeed": "…" } ] }

1–20 packs, each memo once. clientSeed is optional for each pack: sign each memo as for a single open (Seed).

Sell back any number: POST /packs/buyback

{ "memos": ["abcde-5f3c2b1a-…", "abcde-9d01e4c7-…"] }

Any number of memos; a memo listed twice is sold back once. Send up to 10,000 memos per call and split longer lists: a call that returns more results than that may fail even though its cards were sold back. If a call fails, send the same list again: cards already sold back return with "replay": true.

Results

Bulk open and bulk sell-back return one result per pack, in the order you sent them:

{
"results": [
{ "status": 200, "memo": "abcde-5f3c2b1a-…", "success": true, "replay": false, "roll": 41203377, "rarity": "rare", "…": "…" },
{ "status": 503, "memo": "abcde-9d01e4c7-…", "error": "No rare inventory", "code": "NO_INVENTORY" }
]
}
  • HTTP 200 means we read your list. Check each result's status: a result is what the single call returns for that pack (same fields, same codes), plus status and memo.
  • To retry, send the same list again. Finished packs come back with "replay": true.
  • The whole request is refused only with 401, 400 INVALID_JSON or 400 INVALID_MEMOS: not 1–20 packs to open, an empty list to sell back, a malformed memo, or a memo twice in an open.

Instant open: issue and open in one call​

POST /packs/instant issues packs and opens them in the same call, all or nothing. It takes the issue body, and clientRef is required. We generate each pack's seed: the roll verifies at GET /vrf/verify with seedSource: "server", but you cannot sign your own seed on this call. To sign your own, issue and then open. Instant packs get no on-chain VRF commit (vrfCommitSignature stays null); packs opened with your signed seed do, in a batch within about 6 minutes of the open (see Verifying a roll).

{ "packType": "pokemon_50", "playerRef": "user-8431", "clientRef": "order-77120", "count": 5 }
{
"results": [
{ "status": 200, "memo": "abcde-5f3c2b1a-…", "clientRef": "order-77120:1", "price": 50, "success": true, "replay": false, "roll": 41203377, "…": "…" },
{ "status": 200, "memo": "abcde-9d01e4c7-…", "clientRef": "order-77120:2", "price": 50, "success": true, "replay": false, "roll": 7310442, "…": "…" }
]
}
  • All or nothing. Either every pack is issued and opened, and each result has status: 200, or the call returns one error and nothing is issued, opened or billed. For example, if any pack's rarity has no card left, the call returns 503 NO_INVENTORY. When you get an error, send the same call again later.
  • clientRef is required. A call without one returns 400 INVALID_CLIENT_REF. If a call times out, send it again with the same clientRef and count: you get the same packs, not new ones.
  • count is optional, 1–20, as for issue. Without it, one pack is opened under the clientRef you sent; with it, pack n gets <clientRef>:n.
  • Each result is that pack's open result, as in a bulk open, plus its clientRef and price.
  • A clientRef that already holds other packs returns 409 CLIENT_REF_CONFLICT. That covers a different count, or packs issued with POST /packs that were not opened.

Credit limit​

Your credit limit caps the value of the cards you have not paid for yet. It starts at $50,000.

credit left = limit − unpaid cards + USDC on account
  • Unpaid cards: the insuredValue of every card won and not sold back, whether it is held, in the vault or shipped, until the invoice that billed its pack is settled.
  • USDC on account: USDC you have sent that no issued invoice has used yet.
  • Paying an invoice in full returns your credit to the limit, plus whatever is left on account. It never adds more, because the rest of an invoice is not cards.
  • An invoice paid in part frees nothing until it is paid in full.
  • USDC sent before an invoice is issued counts as on account until the invoice is issued and uses it.
Unpaid cardsOn accountCredit left
Start, $50,000 limit$0$0$50,000
October: you keep $10,000 of cards$10,000$0$40,000
October's invoice ($30,000) is issued$10,000$0$40,000
You pay $30,000$0$0$50,000
November: you keep $10,000 of cards$10,000$0$40,000
You send $5,000 before November's invoice$10,000$5,000$45,000
  • When no credit is left, POST /packs and POST /packs/{memo}/open return 503 OUT_OF_CREDITS and write nothing. credits is what is left (zero or negative); memo is present on an open.
    { "error": "Credit limit reached: $50112 of unpaid cards against a $50000 limit. Pay your open invoice, send USDC to your deposit address, sell cards back or ask CollectorCrypt to reset it.",
    "code": "OUT_OF_CREDITS", "memo": "abcde-…", "credits": -112, "retryAfter": 60 }
  • The open that crosses the limit still succeeds. In a bulk open, more than one pack can cross it, and once no credit is left each pack's result is 503 OUT_OF_CREDITS.
  • The limit never blocks a buyback, and each buyback gives back that card's insuredValue at once.
  • There is no cap on money on account, so you can prefund past your limit.
  • A pack refused at open can be opened once credit frees up, until its expiresAt.
  • The partner panel shows your limit, your unpaid cards, what is on account and what remains.

Payments​

Your deposit address is in the partner panel under Payments. It is yours alone.

  • Send USDC on the Solana network to that address, from an exchange or a wallet, at any time. Any other token or network is lost.
  • Within about a minute the amount received goes to your issued invoices, oldest first, and an invoice it pays in full frees its cards from your credit limit. Anything left stays on account and counts as credit until your next invoice uses it.
  • Exchanges can deduct a withdrawal fee, and can add a small fee on your first withdrawal to this address. You are credited what arrives. If it falls short of an invoice, the invoice shows what was applied and stays issued until the rest arrives.
  • Amounts under $1 are credited once the total waiting reaches $1.
  • If your exchange asks who owns the address, it belongs to CollectorCrypt.
  • Add a billing email under Payments to get a confirmation for each payment, and a reminder when you have used 50%, 75% and 90% of your limit.

Users and cards​

  • GET /users/{playerRef} returns counts by state and the number of cards still eligible for buyback:
    { "playerRef": "user-8431", "counts": { "held": 2, "inVault": 5, "shipped": 1, "boughtBack": 3 }, "eligibleBuybacks": 2 }
  • GET /users/{playerRef}/cards?status=custody|shipped|bought_back|all&limit=&cursor= (default custody, meaning held or in_vault) and GET /cards?status=&playerRef=&limit=&cursor= return, newest first:
    { "cards": [ { "memo": "…", "playerRef": "…", "nftAddress": "…", "nft": { }, "insuredValue": 120,
    "acquiredAt": "…", "state": "in_vault", "buybackOpen": false, "buybackExpiresAt": "…",
    "inVault": true, "shippable": true, "releasedAt": null, "releasedReason": null, "shipmentId": null } ],
    "nextCursor": "…" }
    releasedReason is bought_back, shipped or null.
  • GET /users/{playerRef} and GET /users/{playerRef}/cards return 404 for a playerRef you never issued a pack to or saved an address for. Its shipment and address lists are empty.
  • GET /cards/{nftAddress} returns { nftAddress, current, history }. A card can recur if it was bought back and won again.

Your deal​

CollectorCrypt sets one deal on your account. It is fixed on each pack when the pack is issued, like price, so a change applies only to packs issued after it.

  • A % of each pack's price. An opened pack's fee is that % of its price, rounded to the cent. It comes off your invoice as partnerFee, whether the card is kept or sold back.
  • A % of profit. Each invoice credits that % of the profit on the packs it bills, as profitShare. A pack's profit is its price less its buyback credit if the card was sold back, or less the card's insured value if it was kept. You pay for a kept card at its insured value on its own line (see How the total is calculated).
    • A month with a loss credits 0. Your % of that loss is carried forward (shareCarryOut) and paid back from later shares before any is credited. You are never billed for it.
    • A pack's profit is final once its buyback window closes, so a month is issued after its last window closes: about 3 days into the next month (30 days on Development), later if your agreement sets a longer window.
  • None. Any share is added to your invoice by CollectorCrypt as an adjustment.

Invoices and ledger​

  • Invoices cover UTC calendar months. A pack is billed in the month it was opened, a kept card with its pack, a buyback in the month it happened, a shipment in the month you paid it. A row missed by an issued month rolls onto the next invoice.
  • status is draft (provisional; totals as of generatedAt), issued (a bill), settled or void.
  • A negative issued invoice is settled by carrying it into your next one. An invoice that comes to 0 is settled at once. An invoice your payments cover is settled within about a minute.
  • A voided invoice is replaced by a new draft for the same month.

How the total is calculated​

Your users pay you, and CollectorCrypt supplies the cards. A kept card is a cost of its pack, so its insured value comes off the profit, and the profit on the month's packs is split by your deal. You then pay for the cards your users kept, at their insured value, and the shipping CollectorCrypt paid.

  profit                = packsAmount − buybackAmount − keptInsured
CollectorCrypt share = profit − partnerFee − profitShare
total = CollectorCrypt share + keptInsured + shippingAmount + adjustments + carriedForward

The example invoice below, line by line:

  packsAmount              5,000.00   100 packs opened
− buybackAmount 1,800.00 40 cards sold back
− keptInsured 2,700.00 60 cards kept, insured value
= profit 500.00
− partnerFee 0.00
− profitShare 250.00 your 50% of the profit
= CollectorCrypt share 250.00 CollectorCrypt's 50%
+ keptInsured 2,700.00 the 60 kept cards
+ shippingAmount 46.80 2 shipments
+ adjustments −23.40 goodwill credit
+ carriedForward 0.00
= total 2,973.40

GET /invoices and GET /invoices/{id}​

GET /invoices?limit=&cursor= returns { invoices, nextCursor }, newest first. GET /invoices/{id} returns one invoice and its adjustments:

{
"invoice": {
"id": 41, "month": "2026-10", "status": "issued", "provisional": false, "currency": "USD",
"packsCount": 100, "packsAmount": 5000, "partnerFee": 0,
"profitBasis": 500, "profitShare": 250, "shareCarryIn": 0, "shareCarryOut": 0,
"buybackCount": 40, "buybackAmount": 1800,
"keptCount": 60, "keptInsured": 2700,
"shippingCount": 2, "shippingAmount": 46.8,
"adjustments": -23.4, "carriedForward": 0, "carriedFrom": [],
"total": 2973.4, "depositsApplied": 0,
"issuedAt": "2026-11-04T06:00:00.000Z", "settledAt": null, "settlementRef": null,
"voidedAt": null, "replacesInvoiceId": null, "generatedAt": "2026-11-04T06:00:00.000Z"
},
"adjustments": [
{ "id": 7, "amount": -23.4, "reason": "Goodwill credit", "createdAt": "2026-11-03T15:12:00.000Z" }
]
}
FieldMeaning
monthYYYY-MM, UTC
packsCount, packsAmountPacks opened, and their price
partnerFeeYour fee on the packs billed, when your deal is a % of each pack; otherwise 0
profitBasisThe profit on the packs billed that are on a profit share: price, less the buyback credit or a kept card's insured value
profitShareYour % of profitBasis, after paying back shareCarryIn. Never below 0
shareCarryIn, shareCarryOutYour share of past losses still to be paid back, before and after this invoice. Never billed
buybackCount, buybackAmountBuybacks, and their credit
keptCount, keptInsuredCards from the packs billed that were not sold back, and their insured value. Taken off the profit, then added to the total: you pay for the cards your users kept
shippingCount, shippingAmountShipments paid, and their cost: shipping, insurance and any prepaid duties. Added to the total
totalWhat you owe for the month; see How the total is calculated
adjustmentsThe sum of the adjustments' amount. Negative is a credit to you
carriedForward, carriedFromThe negative invoices carried into this one: their total and their ids
depositsAppliedThe USDC payments applied to this invoice so far
issuedAt, settledAt, voidedAtnull until that happens
settlementRefThe payment reference CollectorCrypt recorded; deposits when your USDC payments covered it; carried:<id> when carried into invoice <id>; zero when it came to 0
replacesInvoiceIdThe voided invoice this one replaces, or null
generatedAtWhen the totals were last computed

The list returns the same invoice objects.

GET /ledger​

GET /ledger?limit=&cursor=&invoiceId= returns { events, nextCursor }, oldest first. Each event is { at, type, id, memo, playerRef, amount, shipmentId, invoiceId, partnerFee }. invoiceId= lists exactly one invoice's rows. partnerFee is the pack's fee on pack.created when your deal is a % of each pack, and null otherwise.

typeid is theamount
pack.createdpackits price
pack.awardedawardnull
card.bought_backbuybackits credit
card.escrowed (moved to vault custody)awardnull
shipment.createdshipmentthe quoted cost; null while creating
shipment.paidshipmentthe cost billed
shipment.cancelledshipmentnull
invoice.issued, invoice.settledinvoicethe invoice total
  • memo is set on pack and card events, shipmentId on shipment events, playerRef on all but invoice events.
  • A card shipped before its buyback window closed still moves to vault custody later, so its card.escrowed can come after its shipment events.
  • invoiceId is the invoice that bills the row, null until it is billed. On invoice events it is the invoice itself.
  • id is unique within a type. To poll, repeat the request with a cursor from a few minutes earlier and de-duplicate by type + id: a new event can land just behind your position.

Partner panel​

EnvironmentURL
Productiongacha.collectorcrypt.com/invoiced
Developmentdev-gacha.collectorcrypt.com/invoiced

Sign in with a CollectorCrypt gacha account. Until it is linked, the panel shows its wallet address: send that address to support@collectorcrypt.com and we link it to your partner account. Every change in the panel asks you to approve it with that wallet.

  • Overview: your credit limit and the last 30 days of packs, buybacks and shipping.
  • Payments: your deposit address, billing email, balance on account and payments.
  • API keys: Rotate issues a new key for the same machines and shows it once; the old key keeps working until you revoke it. Revoke stops a key within a minute.
  • Shipping webhook: see Invoiced Shipping.
  • Bills: your invoices.
  • Profit: your deal, the profit by the month packs were opened, and each month's share and loss carried.

Seed (optional)​

Every roll comes from a seed. Omit clientSeed and we generate a random one. To let anyone check that we could not choose it, sign your own: create an Ed25519 key pair, your seed key, register its public half, and send each pack's clientSeed as that key's signature over the pack's memo. Only you can produce it.

You choose per open: with a seed key registered you can still omit clientSeed and get a random seed.

Set up your seed key once​

  1. Generate it. This prints a JSON Web Key: d is the private key, x the public key.

    node -e 'console.log(JSON.stringify(require("crypto").generateKeyPairSync("ed25519").privateKey.export({format:"jwk"})))'
    # → {"kty":"OKP","crv":"Ed25519","x":"<public key>","d":"<private key>"}
  2. Store the whole JSON as a secret on the server that calls this API, next to your API key, for example in the environment variable COLLECTORCRYPT_SEED_KEY. Never put it in a browser or app, and never send it to us: the check only means something while no one else holds the private key.

  3. Register x with PUT /seed-key. Production and Development are separate: register a key on each.

Any Ed25519 library works: d is the 32-byte private key and x the 32-byte public key, both unpadded base64url.

Sign each open​

On your server, sign the memo from POST /packs and send the signature as clientSeed:

// Node
import { createPrivateKey, sign } from 'node:crypto';

const seedKey = createPrivateKey({ key: JSON.parse(process.env.COLLECTORCRYPT_SEED_KEY), format: 'jwk' });

export async function openPack(memo) {
const clientSeed = sign(null, Buffer.from(memo, 'utf8'), seedKey).toString('base64url');
const res = await fetch(`https://gacha.collectorcrypt.com/api/v1/packs/${memo}/open`, {
method: 'POST',
headers: { 'x-api-key': process.env.COLLECTORCRYPT_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ clientSeed }),
});
return res.json();
}
# Python (PyNaCl)
import base64, json, os, nacl.signing

jwk = json.loads(os.environ['COLLECTORCRYPT_SEED_KEY'])
seed_key = nacl.signing.SigningKey(base64.urlsafe_b64decode(jwk['d'] + '='))

def client_seed(memo: str) -> str:
sig = seed_key.sign(memo.encode()).signature
return base64.urlsafe_b64encode(sig).rstrip(b'=').decode()

# POST /packs/{memo}/open with {"clientSeed": client_seed(memo)}
  • The same key and memo always give the same signature, so a retry sends the same clientSeed.
  • A clientSeed must be your seed key's signature over that memo; anything else returns 400 INVALID_SEED.
  • If your private key leaks, register a new one. It cannot open packs or move funds: that takes your API key.

PUT /seed-key, GET /seed-key, DELETE /seed-key​

One key per partner, shared by all your API keys.

curl -X PUT "https://gacha.collectorcrypt.com/api/v1/seed-key" -H "x-api-key: <your key>" -H "Content-Type: application/json" \
-d '{"publicKey":"6kpsY-KcUgq-9VB7Ey7F-ZVHdq6-vnuSQh7qaRRG0iw"}'
# → 200 { "publicKey": "6kpsY-KcUgq-9VB7Ey7F-ZVHdq6-vnuSQh7qaRRG0iw" }
  • PUT sets or rotates the key (null clears it). publicKey is the x of your JWK; anything else returns 400 INVALID_PUBLIC_KEY and changes nothing.
  • GET returns { "publicKey": … }, null when none is registered.
  • DELETE clears it. From then on, sending a clientSeed returns 400 INVALID_SEED; omitting it still works.
  • Rotating affects only packs opened afterwards. Retry an interrupted open with the same clientSeed, or with none: a pack keeps the key it was first opened with, so a retry signed with a newer key can return 400 INVALID_SEED. GET /vrf/verify shows the key a pack was opened under as seedPubkey.

Test vector​

Set COLLECTORCRYPT_SEED_KEY to this key (d is 32 bytes of 0x07; never use it for real packs) and sign the memo:

{"kty":"OKP","crv":"Ed25519","x":"6kpsY-KcUgq-9VB7Ey7F-ZVHdq6-vnuSQh7qaRRG0iw","d":"BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc"}
memoe2ea-00000000-0000-4000-8000-000000000001
clientSeedd8Tuy1t51JKaq9y0XukdEWvy1fxnrfKN1bQ05eT6ASgMGDl1AzZz5wOYo0AN5--QAEaWrq1NiTVIJuXgEur5Cw
alpha8ac322eb53900672b8835f90e97b3fb7683376129ba97e111d5518dec6fbfab1

Verifying a roll​

GET /vrf/verify?memo= is public and needs no key. It returns seedSource (partner or server) and checks:

  • alpha = sha256("ccgacha-ext-v1\0" + memo + "\0" + clientSeed) (\0 is a zero byte);
  • the ECVRF-EDWARDS25519-SHA512-TAI proof, and that the roll equals (first 8 bytes of beta mod 100,000,000) + 1;
  • for a partner seed, that it is your signature over the memo under the key registered when it was used.

valid is true when all of them hold. An unknown or unopened memo returns 404 NOT_FOUND; 404 PROCESSING means an open is still finishing.

A pack opened with your signed seed is also committed on-chain, in a batch every 5 minutes (live on devnet now; on mainnet from the cc-vrf upgrade, date to be announced). Then vrfCommitMode is "batch", vrfCommitSignature is the batch transaction (shared by every pack in it), vrfCommitAddress is null, and vrfBatch gives this pack's index and Merkle path to the batch root. Until the batch lands, vrfCommitSignature is null and vrfBatch.landed is false. vrfVerifyUrl links to the verify page. Packs committed before the switch keep their single-pack commit (vrfCommitMode: "event"). To check a batch yourself, see Checking a batched pack.

Errors​

Every error body is { "error": "…", "code": "…" }; error says what to fix. Some 503s include a Retry-After header. In a bulk open or sell-back, each pack's error is in its result, with the HTTP code as status.

HTTPcodeWhat to do
400INVALID_JSON, INVALID_PLAYER_REF, INVALID_CLIENT_REF, INVALID_COUNT, INVALID_MEMOS, UNKNOWN_MACHINE, INVALID_SEED, INVALID_PUBLIC_KEY, INVALID_STATUS, INVALID_MEMOFix the request
401UNAUTHORIZEDCheck your API key
404NOT_FOUNDUnknown, or not yours
409BUYBACK_WINDOW_CLOSED, MACHINE_NOT_ELIGIBLEFinal; do not retry
409ALREADY_SHIPPINGThe card is in a shipment; cancel it while unpaid to sell the card back
409CLIENT_REF_CONFLICTThat clientRef was used with a different count; resend with that count, or use a new clientRef
409INVENTORY_MISMATCH, NOT_HELDContact us; do not retry
410PACK_EXPIREDNot opened within 2 hours; refund your user or issue a new pack
202PROCESSINGStill finishing; poll
503RAIL_PAUSED, MACHINE_OFF, OFF_BALANCE, MACHINE_LOWRetry later; nothing was written
503OUT_OF_CREDITSYour credit limit is used up. Send USDC, sell cards back or ask CollectorCrypt to reset it, then retry; nothing was written
503VRF_UNAVAILABLE, SELECTION_UNAVAILABLE, NO_INVENTORYRetry the open
500INTERNALRetry with the same clientRef

Shipping errors are on Invoiced Shipping.