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
- Open right after the sale. A pack must be opened within 2 hours of being issued.
- The roll is fixed once the pack is opened. A retry gives the same result. Signing the seed yourself is optional; see Seed.
playerRefandclientRefare your own opaque ids. Never put a name, email, phone number or handle in them.- 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
buybackExpiresAtis 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. - List reads can lag by a few seconds.
GET /packs/{memo}is always current. - A draft invoice is provisional. Only an issued invoice is a bill. A month is issued once its last buyback window has closed.
- 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
| Environment | Base URL |
|---|---|
| Production | https://gacha.collectorcrypt.com/api/v1 |
| Development | https://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.
sellssays whetherPOST /packswould accept a pack now. When it isfalse,blockedCodeis the codePOST /packswould return:RAIL_PAUSED,OUT_OF_CREDITS,MACHINE_OFF,OFF_BALANCE,MACHINE_LOW,MACHINE_NOT_ELIGIBLE,UNKNOWN_MACHINEorINTERNAL.low: truestops sales:POST /packsreturns503 MACHINE_LOW.partnerFeeis 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" }
playerRefis required,^[A-Za-z0-9_-]{1,128}$.clientRefis optional,^[A-Za-z0-9_.:-]{1,128}$. The sameclientRefreturns 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, "…": "…" }
]
}
countis a whole number from 1 to 20. Each item inpacksis 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
playerRefper call. - With
clientRef, pack n gets theclientRef<clientRef>:n, so hereclientRefcan be at most 125 characters. The sameclientRefandcountagain returns the same packs with"replay": true; a differentcountreturns409 CLIENT_REF_CONFLICT. - Without
count,POST /packsissues 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
200means we read your list. Check each result'sstatus: a result is what the single call returns for that pack (same fields, same codes), plusstatusandmemo. - To retry, send the same list again. Finished packs come back with
"replay": true. - The whole request is refused only with
401,400 INVALID_JSONor400 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 returns503 NO_INVENTORY. When you get an error, send the same call again later. clientRefis required. A call without one returns400 INVALID_CLIENT_REF. If a call times out, send it again with the sameclientRefandcount: you get the same packs, not new ones.countis optional, 1–20, as for issue. Without it, one pack is opened under theclientRefyou sent; with it, pack n gets<clientRef>:n.- Each result is that pack's open result, as in a bulk open, plus its
clientRefandprice. - A clientRef that already holds other packs returns
409 CLIENT_REF_CONFLICT. That covers a differentcount, or packs issued withPOST /packsthat 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
insuredValueof 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 cards | On account | Credit 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 /packsandPOST /packs/{memo}/openreturn503 OUT_OF_CREDITSand write nothing.creditsis what is left (zero or negative);memois 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
insuredValueat 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
issueduntil 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=(defaultcustody, meaningheldorin_vault) andGET /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": "…" }releasedReasonisbought_back,shippedornull.GET /users/{playerRef}andGET /users/{playerRef}/cardsreturn404for aplayerRefyou 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 aspartnerFee, 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 itspriceless 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.
- A month with a loss credits 0. Your % of that loss is carried forward (
- 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.
statusisdraft(provisional; totals as ofgeneratedAt),issued(a bill),settledorvoid.- 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" }
]
}
| Field | Meaning |
|---|---|
month | YYYY-MM, UTC |
packsCount, packsAmount | Packs opened, and their price |
partnerFee | Your fee on the packs billed, when your deal is a % of each pack; otherwise 0 |
profitBasis | The profit on the packs billed that are on a profit share: price, less the buyback credit or a kept card's insured value |
profitShare | Your % of profitBasis, after paying back shareCarryIn. Never below 0 |
shareCarryIn, shareCarryOut | Your share of past losses still to be paid back, before and after this invoice. Never billed |
buybackCount, buybackAmount | Buybacks, and their credit |
keptCount, keptInsured | Cards 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, shippingAmount | Shipments paid, and their cost: shipping, insurance and any prepaid duties. Added to the total |
total | What you owe for the month; see How the total is calculated |
adjustments | The sum of the adjustments' amount. Negative is a credit to you |
carriedForward, carriedFrom | The negative invoices carried into this one: their total and their ids |
depositsApplied | The USDC payments applied to this invoice so far |
issuedAt, settledAt, voidedAt | null until that happens |
settlementRef | The payment reference CollectorCrypt recorded; deposits when your USDC payments covered it; carried:<id> when carried into invoice <id>; zero when it came to 0 |
replacesInvoiceId | The voided invoice this one replaces, or null |
generatedAt | When 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.
type | id is the | amount |
|---|---|---|
pack.created | pack | its price |
pack.awarded | award | null |
card.bought_back | buyback | its credit |
card.escrowed (moved to vault custody) | award | null |
shipment.created | shipment | the quoted cost; null while creating |
shipment.paid | shipment | the cost billed |
shipment.cancelled | shipment | null |
invoice.issued, invoice.settled | invoice | the invoice total |
memois set on pack and card events,shipmentIdon shipment events,playerRefon all but invoice events.- A card shipped before its buyback window closed still moves to vault custody later, so its
card.escrowedcan come after its shipment events. invoiceIdis the invoice that bills the row,nulluntil it is billed. On invoice events it is the invoice itself.idis unique within atype. To poll, repeat the request with acursorfrom a few minutes earlier and de-duplicate bytype+id: a new event can land just behind your position.
Partner panel
| Environment | URL |
|---|---|
| Production | gacha.collectorcrypt.com/invoiced |
| Development | dev-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
-
Generate it. This prints a JSON Web Key:
dis the private key,xthe 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>"} -
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. -
Register
xwithPUT /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
clientSeedmust be your seed key's signature over that memo; anything else returns400 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" }
PUTsets or rotates the key (nullclears it).publicKeyis thexof your JWK; anything else returns400 INVALID_PUBLIC_KEYand changes nothing.GETreturns{ "publicKey": … },nullwhen none is registered.DELETEclears it. From then on, sending aclientSeedreturns400 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 return400 INVALID_SEED.GET /vrf/verifyshows the key a pack was opened under asseedPubkey.
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"}
| memo | e2ea-00000000-0000-4000-8000-000000000001 |
| clientSeed | d8Tuy1t51JKaq9y0XukdEWvy1fxnrfKN1bQ05eT6ASgMGDl1AzZz5wOYo0AN5--QAEaWrq1NiTVIJuXgEur5Cw |
| alpha | 8ac322eb53900672b8835f90e97b3fb7683376129ba97e111d5518dec6fbfab1 |
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)(\0is 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.
| HTTP | code | What to do |
|---|---|---|
| 400 | INVALID_JSON, INVALID_PLAYER_REF, INVALID_CLIENT_REF, INVALID_COUNT, INVALID_MEMOS, UNKNOWN_MACHINE, INVALID_SEED, INVALID_PUBLIC_KEY, INVALID_STATUS, INVALID_MEMO | Fix the request |
| 401 | UNAUTHORIZED | Check your API key |
| 404 | NOT_FOUND | Unknown, or not yours |
| 409 | BUYBACK_WINDOW_CLOSED, MACHINE_NOT_ELIGIBLE | Final; do not retry |
| 409 | ALREADY_SHIPPING | The card is in a shipment; cancel it while unpaid to sell the card back |
| 409 | CLIENT_REF_CONFLICT | That clientRef was used with a different count; resend with that count, or use a new clientRef |
| 409 | INVENTORY_MISMATCH, NOT_HELD | Contact us; do not retry |
| 410 | PACK_EXPIRED | Not opened within 2 hours; refund your user or issue a new pack |
| 202 | PROCESSING | Still finishing; poll |
| 503 | RAIL_PAUSED, MACHINE_OFF, OFF_BALANCE, MACHINE_LOW | Retry later; nothing was written |
| 503 | OUT_OF_CREDITS | Your credit limit is used up. Send USDC, sell cards back or ask CollectorCrypt to reset it, then retry; nothing was written |
| 503 | VRF_UNAVAILABLE, SELECTION_UNAVAILABLE, NO_INVENTORY | Retry the open |
| 500 | INTERNAL | Retry with the same clientRef |
Shipping errors are on Invoiced Shipping.