Skip to main content

Shipping API v1

Ship your customers' vaulted cards from your own servers. Your server calls CollectorCrypt with an API key; your customer never signs in to CollectorCrypt. The only thing your customer signs is the redemption itself, on chain, with their own wallet.

What is different from the Shipping API​

Everything you create through v1 lives in your namespace: your API partner account × your customer.

  • Addresses and shipments you create are visible only to you. The same wallet does not see them on collectorcrypt.com, and another partner using the same wallet never sees them.
  • A buyback request is public: it marks the card on collectorcrypt.com as requested for a buyback.
  • You never see your customer's collectorcrypt.com addresses, email, phone number or shipments.
  • CollectorCrypt sends your customer no email, push or in-app notice about a v1 shipment. Poll v1 for status or subscribe to webhooks, and tell your customer yourself. The carrier's own tracking emails go to the contact email you put on the address.
  • You identify customers by your own id (externalId), in the URL path. There is no X-CC-Customer header.
  • Your vault inventory is account-level: GET /vault-items lists the items CollectorCrypt holds in its vault for your account, with no externalId. CollectorCrypt links your account to the customer record it keeps for you; contact support to set it up.
  • Inbound shipments, the boxes your customer sends into the vault, live in your namespace like outbound shipments.

If you integrated the Shipping API with an API key, that integration keeps working. v1 is a separate key and a separate set of routes; move over when you are ready and tell us when you have, so we can retire your old key.

Base URLs​

EnvironmentBase URL
Productionhttps://api.collectorcrypt.com/partner/v1
Devnethttps://dev-api.collectorcrypt.com/partner/v1

Devnet uses Solana devnet and the EVM testnets, including Base Sepolia and Robinhood Chain testnet.

Authentication​

Send your key as a bearer token on every request:

curl https://api.collectorcrypt.com/partner/v1/customers/cust_123 \
-H 'Authorization: Bearer ccsk_...'
  • You create, replace and revoke your keys yourself in the partner console. To get access, email support@collectorcrypt.com with the payment rails you need; we set up your partner account and link your login to it.
  • A key is a server secret. Never ship it to a browser or a mobile app.
  • A v1 key works only on /partner/v1. It is not accepted anywhere else in the API.
  • Revocation takes effect on the next request.

Scopes​

CollectorCrypt grants your account a set of scopes, and each key carries the ones you picked from that set when you created it. A request works only for a scope on both the key and your account, so a scope CollectorCrypt withdraws stops on every key at the next request. A route outside them returns 403 SCOPE_MISSING.

ScopeRoutes
customers:provisionPOST /customers, GET /customers/:externalId
shipping-address/customers/:externalId/addresses/*
redeemestimate, create, burn, signatures, rebuild
outbound-shipmentGET /customers/:externalId/shipments[/:id]
inbound-shipment/customers/:externalId/inbound-shipments/*
vault-itemsGET /vault-items
buybackPOST /customers/:externalId/buybacks. Granted to your account on request; see Buybacks.

Payment rails​

Your account is enabled for one or more rails:

RailCustomerWho paysSection
SolanaA Solana walletThe customer, or your own wallet, in Solana USDC inside the burn transactionSolana redemptions
EVMAn EVM walletThe customer's wallet, on the card's chain (USDC on Base, USDG on Robinhood), with a pay() call next to the burnEVM redemptions
SwapA Solana walletYour swap wallet, in Solana USDC, from a swap your customer signs in your token. Optional, on any Solana shipmentPaying with a swap

The flow​

  1. Register the customer — POST /customers with your externalId and their wallet.
  2. Save an address — POST /customers/:externalId/addresses.
  3. Estimate (optional) — POST /customers/:externalId/shipments/estimate.
  4. Create the shipment — POST /customers/:externalId/shipments. Returns the transactions to sign, or the EVM calls to send.
  5. Your customer signs, and you submit what they signed.
  6. Track — GET /customers/:externalId/shipments/:id until it is Pending, then Shipped and Delivered.

How a shipment is proven​

A shipment moves forward only on evidence that names it:

  • a burn of each of its cards, carrying its shipment id, and
  • a payment carrying its shipment id.

A card that was burned for some other order does not count toward yours, even though the card is gone. So always submit, or let CollectorCrypt observe, the transactions that were built for this shipment.

Limits​

LimitValue
Shipments per page (pageSize)100
Vault items per page (pageSize)100
Wallets per customer1 (Solana or EVM)
externalId length1–160 characters

A person with both a Solana and an EVM wallet is two customers in v1, one per wallet. One shipment holds cards from one chain.

Conventions​

  • JSON in and out. Send Content-Type: application/json and a non-empty User-Agent.
  • Every error has a string code: { "statusCode": 404, "code": "CUSTOMER_UNKNOWN", "message": "..." }. Branch on code, not on message. See Errors.
  • Cost fields are decimal strings in USD.
  • Card identifiers are the same nftAddress values the Shipping API uses: the base58 asset address on Solana, <chain>-<contract>-<tokenId> on EVM. See Card identifiers.

Customers​

POST /customers — scope customers:provision.

FieldTypeRequiredNotes
externalIdstringyesYour id for this customer, 1–160 characters. It goes in every other URL.
walletChainsolana | evmyes
walletstringyesBase58 for Solana; 0x… for EVM (any case, stored lowercase).
curl -X POST https://api.collectorcrypt.com/partner/v1/customers \
-H 'Authorization: Bearer ccsk_...' \
-H 'Content-Type: application/json' \
-d '{"externalId":"cust_123","walletChain":"solana","wallet":"<base58 address>"}'
{ "externalId": "cust_123", "walletChain": "solana", "wallet": "<base58 address>", "created": true, "createdAt": "2026-10-01T12:00:00.000Z" }
  • Idempotent. Posting the same body again returns the same customer with "created": false.
  • An externalId is bound to one wallet for good. Posting it with a different wallet returns 409 CUSTOMER_WALLET_CONFLICT. Register the new wallet under a new externalId.
  • One wallet, one customer. Registering a wallet you already registered under another externalId returns 409 WALLET_ALREADY_REGISTERED.
  • No proof of ownership is needed, and none is asked of your customer. Registering a wallet lets you see what you create, ship its cards once the wallet itself signs the burn, and, with the buyback scope, ask CollectorCrypt for an offer on its cards (Buybacks).
  • Solana smart-contract wallets are not supported (400 WALLET_NOT_SUPPORTED). EVM smart wallets, such as Coinbase Smart Wallet, are supported.

GET /customers/:externalId returns the same object, or 404 CUSTOMER_UNKNOWN.

Every route under /customers/:externalId returns 404 CUSTOMER_UNKNOWN for an id you have not registered. Another partner's customer looks exactly like one that does not exist.

Addresses​

Addresses belong to your customer in your namespace. Your customer never sees them on collectorcrypt.com, and you never see the ones they saved there.

POST /customers/:externalId/addresses — scope shipping-address.

FieldTypeRequiredNotes
fullNamestringyes≤ 128
streetAddressstringyes≤ 256
apartmentstringno≤ 128
citystringyes≤ 128
statestringyesA code or a name; stored as the subdivision name, so "CA" becomes "California". Send an empty string for a country with no subdivisions.
zipstringnoNeeded for correct US rates. ≤ 32
countrystringyesISO 3166-1. Send the two-letter code (GB). Also accepted: the three-letter code (GBR), or the English short name exactly as the iso-3166 package spells it in its name field (United Kingdom of Great Britain and Northern Ireland). Case is ignored. Other spellings are not supported. A value that matches no country is refused with 400 VALIDATION_FAILED. Responses return country as you sent it. List of two-letter codes. Libraries: iso-3166 (JavaScript), pycountry (Python, use alpha_2).
phoneNumberstringyesThe carrier's contact. ≤ 32
emailstringyesThe carrier's contact, and where carrier tracking emails go. Your customer's or your own support address. ≤ 320

Phone and email are always required, and they belong to this address only. Nothing is read from, or written to, your customer's collectorcrypt.com account.

{
"id": "cm...", "fullName": "Ada Lovelace", "streetAddress": "1 Test St", "apartment": null,
"city": "Billings", "state": "Montana", "zip": "59102", "country": "US",
"phoneNumber": "+14065550100", "email": "ada@example.com", "createdAt": "2026-10-01T12:00:00.000Z"
}

Keep id; it is the addressId you ship to.

RouteNotes
GET /customers/:externalId/addresses{ "items": [ … ] }, newest first.
GET /customers/:externalId/addresses/:idOne address, or 404 ADDRESS_NOT_FOUND.
PATCH /customers/:externalId/addresses/:idAny subset of the fields above. The result must still have a phone and an email.
DELETE /customers/:externalId/addresses/:id204. The address can no longer be used for new shipments.

A shipment's address is frozen when it is created: editing or deleting the address later does not change where an existing shipment goes.

Errors: 400 CONTACT_PHONE_REQUIRED · 400 CONTACT_EMAIL_REQUIRED · 400 DESTINATION_RESTRICTED · 400 VALIDATION_FAILED · 404 ADDRESS_NOT_FOUND.

Estimate​

POST /customers/:externalId/shipments/estimate — scope redeem. Optional, for every rail.

FieldTypeRequired
nftAddressesstring[]yes, at least 1
addressIdstringyes
payCustomsDutiesbooleanno

The response is the same as the Shipping API's estimate: price (declared value, not a charge), shippingPrice, insurancePrice, feesPrice, total, customsDutiesEstimate, breakdown. What your customer pays is total. Render breakdown.lines[] generically.

For an EVM customer, estimate refuses the same card sets create does: 400 MIXED_CHAINS and 400 CHAIN_NOT_SUPPORTED. See EVM redemptions.

Solana redemptions​

For a customer registered with a Solana wallet. CollectorCrypt builds the transactions and signs them as fee payer; your customer signs them as the card owner; you submit them. The shipping fee rides inside the first burn transaction, so the burn and the payment land together.

Create a Solana shipment​

POST /customers/:externalId/shipments — scope redeem.

FieldTypeRequiredNotes
nftAddressesstring[]yesCards held by the customer's Solana wallet.
addressIdstringyes
payCustomsDutiesbooleanno
payerWalletstringnoA Solana wallet of yours that pays the fee instead of your customer. It must sign too — see Paying for your customer.
relayBurnbooleannotrue lets a partner program burn its own collection's cards. See Partner-burned cards. Omitted, CollectorCrypt burns every card itself.
{
"outboundShipmentId": "cm...",
"reused": false,
"rail": "solana",
"totalCost": "5.99",
"amountDue": "5.99",
"breakdown": { },
"transactions": ["<base64>"],
"delistTransactions": [],
"partnerBurns": null
}
  • transactions — have your customer's wallet sign every entry, then submit them. The fee is in the first one.
  • partnerBurns — null unless you sent relayBurn: true and the shipment holds cards a partner program burns. See Partner-burned cards.
  • delistTransactions — usually []. Non-empty when a card is listed on an external marketplace and must be released first. Sign and submit these too.
  • reused — posting an identical body again returns the same shipment with fresh transactions. Changing the address, payCustomsDuties or payerWallet creates a new shipment.
  • totalCost is the order's total; amountDue is what is still owed. Both are decimal strings.
Sign and submit within about a minute

A Solana transaction carries a recent blockhash and expires roughly 60–90 seconds after it was built. If yours expires, call rebuild; do not create a new shipment.

Submit through CollectorCrypt​

POST /customers/:externalId/shipments/:id/burn — scope redeem.

{ "transactions": ["<base64 signed>"], "delistTransactions": [] }

CollectorCrypt checks that these are exactly the transactions it built for this shipment, broadcasts them and waits for confirmation. The response is an array, one element per transaction:

[{ "error": null, "transactionId": "<signature>", "transactionUrl": "https://..." }]

Inspect every element: a non-null error means that transaction did not land. Transactions CollectorCrypt did not build for this shipment are refused with 403 BATCH_NOT_ISSUED.

Report transactions your customer's wallet sent​

Many wallets sign and send in one step. That is fine; report what landed.

POST /customers/:externalId/shipments/:id/signatures — scope redeem.

{ "signatures": ["<signature>", "<signature>"] }
[
{ "signature": "<signature>", "status": "linked" },
{ "signature": "<signature>", "status": "pending" }
]
statusMeaning
linkedConfirmed, verified as this shipment's, and recorded.
pendingNot confirmed yet. Report it again in a few seconds.
rejectedNot a transaction CollectorCrypt built for this shipment. reason says why.

A transaction is accepted only if CollectorCrypt's own key paid its network fee and its memo names this shipment. Only CollectorCrypt can produce that signature, which proves the landed transaction is the one built for this order. Two exceptions, both bound by the memo: a partner program's burns of this shipment's cards, and a transaction paying exactly the order total in USDC (Tx A on a swap). Reporting the same signature twice is safe.

Report the burn transactions. A delistTransactions signature needs no report; if you include one it comes back rejected with reason not a burn transaction for this shipment, and the rest of the report is still processed.

Use this route too if a burn call timed out: report the signatures and the shipment catches up.

Rebuild expired transactions​

POST /customers/:externalId/shipments/:id/rebuild — scope redeem.

Returns fresh transactions and delistTransactions for the cards on this shipment that have not burned yet, in the same shape as create, plus feeReCollected (whether the fee is in this batch) and remainingCards. Before building, CollectorCrypt looks for transactions of this shipment that your customer's wallet already sent, so a fee that landed is never charged again. Use it when the blockhash expired, after some transactions of a multi-transaction shipment failed, or after a batch is refused with BATCH_NOT_ISSUED because it is older than 15 minutes. For an EVM shipment, see Get the remaining calls. On a swap shipment, send the four swap fields again as the body, and relayBurn: true again if you sent it on create.

Paying for your customer​

Send payerWallet on create. The fee instruction in the first transaction is then paid from that wallet, so that transaction needs two signatures: your payer's and your customer's. CollectorCrypt pays the network fee either way. payerWallet is Solana-only.

Errors: 400 CARD_NOT_REDEEMABLE · 404 CARDS_NOT_FOUND · 400 MIXED_CHAINS · 400 INSUFFICIENT_BALANCE · 403 RAIL_NOT_ENABLED · 403 BATCH_NOT_ISSUED · 403 BATCH_INCOMPLETE · 409 DELIST_FAILED · 409 SHIPMENT_NOT_MODIFIABLE.

Partner-burned cards​

Some collections can be burned by their own on-chain program rather than by CollectorCrypt: today, RipMart's, on devnet. This is opt-in. Send relayBurn: true on create. Without it, nothing changes: CollectorCrypt builds the burns for every card, RipMart's included, exactly as in Solana redemptions.

One shipment can hold those cards, CollectorCrypt cards, or both. With relayBurn: true, CollectorCrypt puts Tx A first in transactions. Tx A carries the fee and your customer's consent to the partner program burning exactly these cards for this shipment (RipMart's redeem_open). CollectorCrypt pays its network fee and the consent account's rent. The burns for CollectorCrypt cards follow it, with no fee on them.

{
"outboundShipmentId": "cm...",
"reused": false,
"rail": "solana",
"totalCost": "5.99",
"amountDue": "5.99",
"breakdown": { },
"transactions": ["<base64 Tx A>", "<base64 CollectorCrypt burn>"],
"delistTransactions": [],
"partnerBurns": {
"programId": "8q64n8Dybj6wkF39pDVQQ7iRgn6YeTdpuf7WVi8s7Bxi",
"consent": "<consent account address>",
"merkleRoot": "<hex>",
"items": ["<nftAddress>", "<nftAddress>"]
}
}
  1. Your customer signs every transaction, in one wallet prompt. Submit them all through burn. Tx A landing pays the shipment and records the consent.
  2. Ask the partner to burn. For RipMart, call redeem.execute in the RipMart SDK with the shipment id, your customer's wallet and partnerBurns.items, unchanged and in order. The partner checks that list against the consent on chain.
  3. The partner burns each card in its own transaction, carrying the memo cc shipment: <id>. CollectorCrypt links each burn as it lands. The shipment reaches Pending once it is paid and every card is burned.
  • items — the partner cards on the shipment, sorted. It is the leaf order of the consent; the same shipment always gives the same items and merkleRoot.
  • rebuild — send relayBurn: true again. It returns Tx A while the consent has not landed; once it has, Tx A is left out.
  • GET /customers/:externalId/shipments/:id re-checks your customer's wallet for burns not yet linked. Call it once after the partner's last burn lands; use webhooks for everything after that.

A card that becomes unburnable after Tx A lands, for example sold or consigned, leaves the shipment at PaymentReceived. Contact support.

Paying with a swap​

When your customer holds no USDC, your swap wallet pays CollectorCrypt for them, from a swap your customer signs. Send these four fields on create, all together. Any Solana shipment can use them, with or without partner-burned cards.

FieldTypeNotes
swapWalletstringYour wallet that pays CollectorCrypt the USDC. It signs Tx A and pays its network fee.
swapMintstringThe token your customer pays you in. SPL Token or Token-2022.
swapAmountstringYour customer's side, in swapMint base units. Your rate.
expectedTotalstringThe total you quoted, as a decimal USD string, e.g. "5.99". Take it from estimate.

If the total has moved since your estimate, create returns 409 TOTAL_CHANGED. Estimate again, re-quote your customer, and retry.

The response has the Solana shape with "rail": "swap". Tx A, first in transactions, is then:

  • your customer pays swapAmount of swapMint to your swap wallet;
  • your swap wallet pays exactly totalCost USDC to CollectorCrypt;
  • the partner consent, when you sent relayBurn: true and the shipment has partner-burned cards;
  • the memo.

Your swap wallet is Tx A's fee payer and pays the rent for its own token account and for the consent, so keep a little SOL there. CollectorCrypt adds one signature to Tx A, on an instruction that touches no account. No wallet can change Tx A after it is built, and CollectorCrypt pays nothing in it.

  1. Check Tx A before your swap wallet signs it: it spends your USDC.
  2. Sign Tx A with your swap wallet. Your customer signs every transaction, in one wallet prompt.
  3. Submit them all through burn.

On rebuild, send the same four fields: Tx A is rebuilt with a fresh swap. A swap shipment that still owes refuses a rebuild without them, and a USDC shipment refuses them, both with 400 VALIDATION_FAILED. Once the shipment is paid, rebuild needs no swap.

Errors: 409 TOTAL_CHANGED · 400 VALIDATION_FAILED · and the Solana redemption errors.

EVM redemptions​

For a customer registered with an EVM wallet. The customer's wallet sends the burn and the payment itself; CollectorCrypt signs nothing.

Payment is on the card's chain: USDC on Base, USDG on Robinhood. One shipment holds cards from one chain (MIXED_CHAINS), so the burn and the payment go to the same chain. A card on any other EVM chain is refused with CHAIN_NOT_SUPPORTED.

ChainTokenProductionDevnet
BaseUSDC0x833589fcd6edb6e08f4c7c32d4f71b54bda029130x036cbd53842c5426634e7929541ec2318f3dcf7e
Robinhood ChainUSDG0x5fc5360d0400a0fd4f2af552add042d716f1d1680x7e955252e15c84f5768b83c41a71f9eba181802f

The create response names the token in payment.token. Both tokens have 6 decimals.

Create an EVM shipment​

POST /customers/:externalId/shipments — scope redeem. Body: nftAddresses, addressId, payCustomsDuties.

evmCallBundle.calls is what your customer's wallet sends, in order: approve, the burns, pay. A batchBurn takes at most 50 cards, so there is one batchBurn per 50 cards: a 120-card shipment has three.

{
"outboundShipmentId": "cm...",
"reused": false,
"rail": "evm",
"totalCost": "5.99",
"amountDue": "5.99",
"breakdown": { },
"evmCallBundle": {
"chainId": 8453,
"atomicPreferred": true,
"calls": [
{ "kind": "approve", "to": "0x...", "value": "0", "data": "0x..." },
{ "kind": "batchBurn", "to": "0x...", "value": "0", "data": "0x..." },
{ "kind": "pay", "to": "0x...", "value": "0", "data": "0x..." }
],
"payment": {
"chain": "base", "chainId": 8453, "payer": "0x...", "token": "0x...", "spender": "0x...",
"amountRaw": "5990000", "memo": "cm...", "amountDue": "5.99"
}
},
"payment": { },
"evmTransactions": [
{ "chain": "base", "chainId": 8453, "tokenIds": ["492"], "owner": "0x...",
"burnTxs": [{ "to": "0x...", "data": "0x...", "chainId": 8453, "gas": "..." }] }
]
}
  • Every batchBurn carries the shipment id as its memo, and so does pay (payment.memo). That is what ties them to this shipment.
  • approve grants exactly the amount due, never an unlimited allowance.
  • amountRaw is in the token's 6-decimal units (5990000 is 5.99). The amount is fixed when the shipment is created.
  • chainId is the cards' chain. The example is a Base card; a Robinhood card returns "chain": "robinhood", chainId 4663 (devnet 46630), and USDG as token.
  • payment repeats evmCallBundle.payment.
  • evmTransactions lists the same burns: one burnTxs entry per batchBurn, in the same order, and the tokenIds they burn. With an evmCallBundle, they are already in its calls; do not send them twice.
  • burnTxs[].gas is a gas limit for that batchBurn: CollectorCrypt's estimate plus 30%. evmCallBundle.calls carry none. A group of 50 cards or fewer also has burnTx, the same call as its only burnTxs entry; read burnTxs.

Errors: 400 CARD_NOT_REDEEMABLE · 404 CARDS_NOT_FOUND · 400 MIXED_CHAINS · 400 CHAIN_NOT_SUPPORTED (the cards' chain has no payment token) · 400 VALIDATION_FAILED (payerWallet or a swap field) · 403 RAIL_NOT_ENABLED · 409 CUSTOMER_WALLET_UNLINKED · 503 UNAVAILABLE (payment is unavailable on that chain; retry later).

Send the calls​

Send from payment.payer, the wallet holding the cards, on evmCallBundle.chainId. Every call in the bundle goes to that one chain; a wallet connected to another chain must switch first.

  • Wallets with EIP-5792, such as Coinbase Smart Wallet: send evmCallBundle.calls as one wallet_sendCalls batch, with atomicRequired: true where the wallet supports it. Run atomically, the burns and the payment succeed or fail together.
  • Other wallets: send each call in order with eth_sendTransaction, waiting for each receipt. Every batchBurn comes before pay; if one reverts, stop — nothing has been charged.

An atomic wallet_sendCalls batch lands as one transaction, so it has to fit under the chain's gas limit per transaction. As a rough guide, that is about 16.8M gas on Base, or around 6 batchBurn calls (300 cards), and 32M on Robinhood, or around 10 (500 cards). A batch over the limit is refused before it is sent, so nothing burns or pays: send the calls one by one, in order, instead.

Sent one by one, the calls can stop part-way. If a batchBurn reverts after earlier ones landed, their cards stay burned and nothing has been charged. Fix the cause, then send the calls that have no successful receipt, in order, from the same create response; its calls do not expire. Or get the remaining calls.

Report the burn​

Recommended. CollectorCrypt reads the burns and the Paid event from the chain and matches them to the shipment by memo, but a burn it misses is recorded only when you report it. Send every hash that carries a batchBurn, one evmTransactions entry per hash:

POST /customers/:externalId/shipments/:id/burn — scope redeem.

{ "evmTransactions": [{ "chain": "base", "txHash": "0x..." }] }
[{ "txHash": "0x...", "status": "confirmed" }]
statusMeaning
confirmedMined, and it burned this shipment's cards with this shipment's memo. Recorded.
pendingNot mined within the wait, or its receipt could not be read. Each hash waits up to about 20 seconds, and one report waits about 40 seconds in all. Nothing was recorded. Report it again, or let CollectorCrypt pick it up.
rejectedReverted, or not a burn for this shipment. reason says why.

A hash is only ever recorded after it is verified on chain, so reporting early or reporting the wrong hash cannot mark anything. A report holds at most as many hashes as the shipment has cards; more returns 400 VALIDATION_FAILED.

On this rail, PaymentPending means every burn is recorded and no payment has been credited yet. If your customer's wallet has not sent pay, send the approve and pay calls; if you no longer have them, get the remaining calls. If it has, do not send another: a pay is credited after enough confirmations, usually within about 5 minutes, and a second pay charges your customer again.

Errors: 400 VALIDATION_FAILED · 404 SHIPMENT_NOT_FOUND · 409 SHIPMENT_NOT_MODIFIABLE (cancelled, ActionRequired, or Pending and later).

Get the remaining calls​

POST /customers/:externalId/shipments/:id/rebuild — scope redeem. No body: the swap fields and relayBurn: true are Solana-only.

The same route as the Solana rebuild, but nothing is re-signed: EVM calls do not expire. It returns the calls this shipment still needs, worked out from what CollectorCrypt has recorded, in the same shape as create, plus feeReCollected (whether pay is in the bundle) and remainingCards. Use it when a call reverted part-way, when you lost the create response, or when the shipment is PaymentPending and pay was never sent. Report the hashes that landed first: only cards CollectorCrypt has recorded as burned are left out.

ShipmentevmCallBundleevmTransactions
Cards left, not paidapprove, one batchBurn per 50 cards left, payThe same burns
Cards left, paidnull, and so is paymentThe burns: send each burnTxs entry, in order
Every card burned, not paidapprove, pay[]

pay is the one frozen at create: same amount, token and chain. Once CollectorCrypt has seen a pay for this shipment, it does not return another: you get the burns alone, or 409 SHIPMENT_NOT_MODIFIABLE when every card is burned. Seeing a pay can take up to about 5 minutes, and until then this route still returns one. So if your customer's wallet has a successful pay receipt for this shipment, never send another, whatever this route returns: a second pay charges your customer again and is not credited. A pay CollectorCrypt does not credit, for example one below amountRaw, stops counting; contact support about it.

Errors: 400 VALIDATION_FAILED (a swap field or relayBurn: true) · 403 RAIL_NOT_ENABLED · 404 SHIPMENT_NOT_FOUND · 409 SHIPMENT_NOT_MODIFIABLE (cancelled; ActionRequired; every card burned and paid; every card burned and a payment seen; a burned card no reported burn lists, so report its hash first; or no payment is frozen for this shipment) · 409 TOTAL_CHANGED (the payment no longer matches the one frozen at create; contact support) · 409 CUSTOMER_WALLET_UNLINKED · 503 UNAVAILABLE (retry in a minute; if a burn landed and is not recorded yet, report its hash first).

Track shipments​

CollectorCrypt does not email or notify your customer about v1 shipments. Poll these routes or subscribe to webhooks, and keep your customer informed yourself. The carrier's own tracking emails go to the email on the shipment's address.

One shipment​

GET /customers/:externalId/shipments/:id — scope outbound-shipment. Returns the shipment, or 404 SHIPMENT_NOT_FOUND.

{
"id": "cm...", "customId": "2026100100OS123", "status": "Shipped",
"numberOfCards": "1", "nftAddresses": ["..."], "addressId": "cm...",
"shippingCost": "5.99", "insuranceCost": "0.00", "feesCost": "0.00", "totalCost": "5.99",
"dutiesPrepaid": false, "dutiesPrepaidAmount": null,
"paymentMethod": "crypto", "paymentRail": "solana", "paymentConfirmedAt": "2026-10-01T12:05:00.000Z",
"trackingIds": ["1Z..."], "trackingUrls": ["https://..."],
"payment": null,
"createdAt": "2026-10-01T12:00:00.000Z", "updatedAt": "2026-10-02T09:00:00.000Z"
}
  • Cost fields and numberOfCards are strings.
  • payment is the frozen EVM payment intent (chain, token, spender, amountRaw, memo, paid) on the EVM rail, and null otherwise. It lets you recover what is owed if you lost the create response.
  • customId is the order number CollectorCrypt's warehouse and support use.

List shipments​

GET /customers/:externalId/shipments — scope outbound-shipment. Newest first.

QueryNotes
statusComma-separated statuses, e.g. Pending,Processing,Shipped.
createdFrom, createdToISO 8601.
pageSizeUp to 100. Default 100.
cursorLeave it out for the first page. After that, the previous response's nextCursor, unchanged.

Request the first page without cursor, then pass each response's nextCursor back as cursor until it is null. Keep status, createdFrom and createdTo the same for the whole walk. A cursor this route did not issue returns 400 VALIDATION_FAILED, and so does a page greater than 1.

curl 'https://api.collectorcrypt.com/partner/v1/customers/cust_123/shipments?pageSize=50' \
-H 'Authorization: Bearer ccsk_...'
curl 'https://api.collectorcrypt.com/partner/v1/customers/cust_123/shipments?pageSize=50&cursor=eyJ2IjoxLCJzY29wZSI6InBhcnRuZXItdjEtc2hpcG1lbnRzIi...' \
-H 'Authorization: Bearer ccsk_...'
{ "items": [ { "id": "cm...", "status": "Shipped", ... } ], "page": 1, "pageSize": 50, "total": 73, "nextCursor": "eyJ2IjoxLCJzY29wZSI6InBhcnRuZXItdjEtc2hpcG1lbnRzIi..." }
  • Each item is the object One shipment returns.
  • total counts every shipment that matches the filters. page is always 1.

Statuses​

StatusMeaning
CreatedCreated; not yet paid or burned.
PaymentPendingBurn recorded, payment not yet credited (EVM).
PaymentReceivedPaid, burn not yet recorded.
PendingPaid and burned. Accepted by the warehouse.
ProcessingBeing packed.
ShippedHanded to the carrier. trackingIds are set.
DeliveredDelivered.
ActionRequiredNeeds CollectorCrypt's attention — email support with the customId.
CancelledCancelled.

Treat these as a set, not a sequence: a shipment can skip states, and it never moves backwards.

Inbound shipments​

Send boxes of graded cards into CollectorCrypt's vault for a customer. Provision the customer first, as for an outbound shipment. Every route needs scope inbound-shipment.

Inbound shipments live in your namespace, like outbound ones: only you see them, never the customer's own collectorcrypt.com account or another partner using the same wallet.

Who owns what arrives:

  • Your account is linked to a customer record (see Vault items): every item the shipment carries is registered to that record and appears in GET /vault-items. CollectorCrypt does not mint it.
  • No customer record: the items are registered to CollectorCrypt, as for a shipment created on collectorcrypt.com.

The flow:

  1. Create the shipment. Note its id and shipTo.
  2. Add the cert numbers of the cards in the box.
  3. Write the shipment id on the box and send it to shipTo.
  4. Add the tracking number. The shipment becomes Shipped.
  5. Poll the shipment and its vault items. Inbound shipments send no webhook.

CollectorCrypt sends your customer no email, push or in-app notice about an inbound shipment.

Create an inbound shipment​

POST /customers/:externalId/inbound-shipments — scope inbound-shipment.

FieldTypeRequiredNotes
numberOfCardsintegeryes1–100000. How many cards the box holds.
descriptionstringnoUp to 160 characters.
valueOfBoxnumbernoThe declared value in USD, 0 or more, at most 2 decimal places.
curl -X POST https://api.collectorcrypt.com/partner/v1/customers/cust_123/inbound-shipments \
-H 'Authorization: Bearer ccsk_...' \
-H 'Content-Type: application/json' \
-d '{"numberOfCards":25,"description":"November restock","valueOfBox":12500}'
{
"id": "2026111114S855",
"status": "New",
"description": "November restock",
"numberOfCards": 25,
"numberOfCardsReceived": null,
"valueOfBox": "12500.00",
"trackingId": null,
"trackingUrl": null,
"shipTo": ["PWCC Vault:", "Collector Crypt #732795", "7560 SW Durham Rd", "Tigard, OR 97224"],
"parcels": [],
"createdAt": "2026-11-11T18:00:00.000Z",
"updatedAt": "2026-11-11T18:00:00.000Z"
}
FieldTypeNotes
idstringCollectorCrypt's id for the shipment. Write it on the box.
statusstringSee Inbound statuses.
descriptionstring | null
numberOfCardsintegerThe count you declared.
numberOfCardsReceivedinteger | nullThe count the vault received.
valueOfBoxstringThe declared value in USD, to the cent.
trackingId, trackingUrlstring | nullThe last tracking number added, and its carrier link.
shipTostring[]The address lines to send the box to.
parcelsobject[]One per tracking number added: trackingNumber, carrierCode, status, statusAt, deliveredAt.
createdAt, updatedAtstringISO 8601.

Add cert numbers​

POST /customers/:externalId/inbound-shipments/:id/certs — scope inbound-shipment.

FieldTypeRequiredNotes
certIdsstring[]yes1–2000 cert numbers. Letters and digits only, up to 32 characters each. Repeats are dropped.
gradingCompanystringnoA hint for which grader to look the certs up with first: PSA, PSA/DNA, CGC, CGC Trading Cards, Beckett or BGS.
{ "added": ["123456789"], "skipped": [{ "cert": "987654321", "reason": "duplicate" }] }

Each cert comes back once, in added or in skipped. duplicate means the cert is already in the vault, or already on this shipment. A shipment holds at most 5000 certs; past that the request returns 400 VALIDATION_FAILED. CollectorCrypt looks up each added cert's card name, set and grade in the background; read them from the shipment's vault items.

Certs can be added while the shipment is Draft, New or Shipped. After that the request returns 409 SHIPMENT_NOT_MODIFIABLE.

Update an inbound shipment​

PATCH /customers/:externalId/inbound-shipments/:id — scope inbound-shipment. Send any of description, numberOfCards, valueOfBox (same rules as create) and trackingId.

  • description, numberOfCards and valueOfBox can change while the shipment is Draft, New or Shipped.
  • trackingId can be added in the same states. It makes the shipment Shipped and adds a parcel. Add one per box: earlier numbers stay in parcels.
  • Anything else returns 409 SHIPMENT_NOT_MODIFIABLE. An empty body returns 400 VALIDATION_FAILED.

Returns the shipment.

Cancel and resume​

POST /customers/:externalId/inbound-shipments/:id/cancel — scope inbound-shipment. Only a New shipment can be cancelled.

POST /customers/:externalId/inbound-shipments/:id/resume — scope inbound-shipment. Returns a Canceled shipment to New.

Both return the shipment, or 409 SHIPMENT_NOT_MODIFIABLE from any other status.

One inbound shipment​

GET /customers/:externalId/inbound-shipments/:id — scope inbound-shipment. Returns the shipment, or 404 SHIPMENT_NOT_FOUND.

List inbound shipments​

GET /customers/:externalId/inbound-shipments — scope inbound-shipment. Newest first.

QueryNotes
statusComma-separated statuses. Leave it out for every status.
pageSize1–100. Default 100.
cursorLeave it out for the first page. After that, the previous response's nextCursor, unchanged.
{ "items": [ { "id": "2026111114S855", "status": "Shipped", "...": "..." } ], "pageSize": 100, "nextCursor": null }

Paging works as for vault items: no page and no total.

A shipment's vault items​

GET /customers/:externalId/inbound-shipments/:id/vault-items — scope inbound-shipment. Every item registered on the shipment, newest first, in one response:

{ "items": [ { "id": "cm...", "status": "Expected", "cert": "123456789", "...": "..." } ] }

Each item is the same object as GET /vault-items returns. An added cert starts as Expected and becomes Vaulted when the vault scans it. Later it can become Sent when it ships out, or Gone if the vault cannot find it during an audit.

Inbound statuses​

statusMeaning
DraftStarted on collectorcrypt.com and not submitted. v1 never creates one.
NewCreated. No tracking yet.
ShippedA tracking number was added.
ReceivedThe vault has the box.
ProcessingThe vault is scanning the items in.
AwaitingMint, PartlyMinted, FullyMintedCollectorCrypt is minting the items it owns.
CanceledCancelled. It can be resumed.

Vault items​

List the items CollectorCrypt holds in its vault for your account. The route is account-level: it takes no externalId.

GET /vault-items — scope vault-items. CollectorCrypt links your account to the customer record it keeps for you; until it has, this route returns 403 VAULT_NOT_ENABLED. Email support@collectorcrypt.com to set it up.

QueryNotes
searchMatches part of the cert number, card name, set or vault handle. Case is ignored.
certComma-separated cert numbers, matched exactly.
statusComma-separated statuses, e.g. Vaulted,Sent. Leave it out for every status.
typeComma-separated item types, e.g. Card,CardRaw.
gradingCompanyComma-separated graders, exactly as items return them, e.g. PSA,CGC,Beckett.
createdFrom, createdToISO 8601, compared with createdAt. Both bounds are included.
pageSize1–100. Default 100.
cursorLeave it out for the first page. After that, the previous response's nextCursor, unchanged.

Every parameter is optional. A list can also repeat its parameter: status=Vaulted&status=Sent is the same as status=Vaulted,Sent.

Items come newest first, by createdAt. Request the first page without cursor, then pass each response's nextCursor back as cursor until it is null. Keep every filter the same for the whole walk. There is no page parameter and no total. A cursor this route did not issue returns 400 VALIDATION_FAILED, and so does page or any other parameter not in the table above.

curl 'https://api.collectorcrypt.com/partner/v1/vault-items?status=Vaulted&search=charizard&pageSize=50' \
-H 'Authorization: Bearer ccsk_...'
{
"items": [
{
"id": "cm...", "status": "Vaulted", "type": "Card",
"gradingCompany": "PSA", "cert": "123456789", "grade": "GEM-MT 10",
"cardName": "Charizard-Holo", "set": "Pokemon Base Set", "year": "1999", "cardNumber": "4",
"category": "Pokemon", "vaultHandle": null,
"media": [
{ "type": "ImageFront", "source": "Vault", "url": "https://...", "urlMedium": "https://...", "urlSmall": "https://..." },
{ "type": "ImageBack", "source": "Vault", "url": "https://...", "urlMedium": "https://...", "urlSmall": "https://..." }
],
"scannedAt": "2026-10-01T12:00:00.000Z", "createdAt": "2026-09-28T15:30:00.000Z"
}
],
"pageSize": 50,
"nextCursor": null
}
FieldTypeNotes
idstringCollectorCrypt's id for the item.
statusstringExpected, Vaulted, Sent or Gone. See below.
typestringCard, CardRaw, Comic, ComicRaw, Watch or Product. CardRaw and ComicRaw are ungraded. A Product is a non-card good, such as a boxed set or a video game: cardName is its title, and cert and grade are null.
gradingCompanystring | nullThe grader, e.g. PSA.
certstring | nullThe grader's cert number.
gradestring | nullThe grade as the grader labels it, e.g. GEM-MT 10.
cardNamestring | nullThe card's name.
setstring | nullThe set's name.
yearstring | nullThe card's year.
cardNumberstring | nullThe card's number in its set.
categorystring | nullThe game, e.g. Pokemon.
vaultHandlestring | nullThe vault's own handle for an item with no cert, such as the QR label on an ungraded card. A graded slab is identified by cert instead.
mediaobject[]Photos and video, newest first. Can be empty.
media[].typestringImageFront, ImageBack, ImageExtra or Video.
media[].sourcestringVault: added by CollectorCrypt's vault. Grader: from the grading company.
media[].urlstring | nullThe full-size file.
media[].urlMedium, media[].urlSmallstring | nullSmaller copies of url.
scannedAtstring | nullISO 8601. When the item was scanned into the vault. null when no scan is recorded, as for an Expected item.
createdAtstringISO 8601. When CollectorCrypt first recorded the item.
statusMeaning
ExpectedRegistered, not yet received.
VaultedIn the vault.
SentShipped out of the vault.
GoneThe vault could not find it during an audit, and we do not know why. If it turns up, it goes back to Vaulted.

Media URLs can change, and some, such as Grader URLs, may be hosted by the grading company. Read them fresh from this route rather than storing them.

Items assigned to another account never appear, even when you filter by their cert.

Buybacks​

Ask CollectorCrypt to make an offer on your customer's cards. A request is a review: it is not a sale and not a price.

POST /customers/:externalId/buybacks — scope buyback, which CollectorCrypt grants to your account on request. Email support@collectorcrypt.com, then create a key that carries it.

FieldTypeRequiredNotes
nftAddressesstring[]yes1–200 card identifiers: Solana mint addresses for a Solana customer, <chain>-<contract>-<tokenId> for an EVM customer.
curl -X POST https://api.collectorcrypt.com/partner/v1/customers/cust_123/buybacks \
-H 'Authorization: Bearer ccsk_...' \
-H 'Content-Type: application/json' \
-d '{"nftAddresses":["base-0x1ffd5353ae2f29758b811fa9f9146c1f59e6e9e7-492"]}'
{ "requested": ["base-0x1ffd5353ae2f29758b811fa9f9146c1f59e6e9e7-492"], "refused": [] }

Each card comes back once, in the form CollectorCrypt stores (an EVM chain and contract in lowercase): in requested, or in refused with a code.

codeMeaning
CARDS_NOT_FOUNDThe card does not exist, is not on the chain of this customer's wallet, or this customer's wallet does not hold it.
CARD_NOT_REDEEMABLEThe customer holds the card, but it is not in a state CollectorCrypt makes offers on (for example burned).
  • Idempotent. A card already waiting for review comes back in requested again.
  • Public. Anyone can list a requested card with the Requested Buyback filter on the collectorcrypt.com marketplace, and the card's public data carries getBuybackOffer: true.
  • The offer on an EVM card. If CollectorCrypt makes one, it is an OpenSea (Seaport) bid on the token, in the chain's USD stablecoin (USDC; USDG on Robinhood Chain), open for 3 days. It appears among the token's offers on OpenSea. Your customer's wallet accepts it there by signing the fulfilment and paying the gas.
  • The offer on a Solana card. If CollectorCrypt makes one, it is a USDC offer on CollectorCrypt's own marketplace. It appears on the card's page on collectorcrypt.com, and your customer accepts it there with the same wallet. v1 has no route to accept it.
  • No email. CollectorCrypt does not email your customer about the request or the offer. Tell them yourself.
  • The queue. The card leaves the review queue when the offer is posted, when CollectorCrypt declines, or when the card is transferred. A declined card can be requested again.
  • Devnet accepts EVM requests and never posts a bid: OpenSea trading is off there.

Errors for the whole request:

StatuscodeMeaning
400WALLET_NOT_SUPPORTEDThis wallet cannot request buybacks through the API.
400VALIDATION_FAILEDnftAddresses is missing, empty or longer than 200.
409CUSTOMER_WALLET_UNLINKEDThe account this customer was linked to no longer holds the wallet. Contact support.

Webhooks​

CollectorCrypt can POST to your server when one of your v1 shipments changes. Webhooks do not replace the API: the GET routes above remain the source of truth.

Endpoint​

You have one endpoint per API partner account, set in the partner console. The URL must:

  • use https;
  • point to a public address. Private, loopback, link-local and cloud-metadata addresses are refused when you save the URL, and again at every connection;
  • be at most 2048 characters;
  • contain no credentials (https://user:pass@… is refused).

While your webhook is disabled, changes are not queued. Disabling it also drops any event still waiting for a retry, and enabling it again does not replay them. List your shipments to catch up.

Events​

typeSent when
shipment.updatedA v1 shipment's status or trackingIds change, or you send a test event.
pingYou send a test from the partner console. data is {}. Sent once, never retried; the console shows the result.

Test events​

In the partner console, pick a status under Test event status and press Send test event. Your webhook receives one signed shipment.updated with that status. Nothing changes on any shipment, so you can send as many as you like, on Devnet and Production.

  • The event id starts with test.. Headers and signing are the same as for real events.
  • data.shipment is a sample, not one of your shipments: its id is test-shipment, its customId is TEST, its addressId is null and its nftAddresses is empty. data.customerExternalId is null.
  • Shipped and Delivered carry the UPS test tracking number 1Z999AA10123456784.
  • A test event is sent once and never retried; the console shows the result.

Request​

POST to your URL, with these headers:

HeaderValue
Content-Typeapplication/json
User-AgentCollectorCrypt-Webhooks/1
CC-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>. See Verify the signature.
{
"id": "3f0c2a9e-5b7d-4c1e-9a8f-6d2b1e0c7a43.2",
"type": "shipment.updated",
"createdAt": "2026-10-02T12:00:00.000Z",
"data": {
"customerExternalId": "cust_123",
"shipment": { }
}
}
  • data.shipment is exactly the object GET /customers/:externalId/shipments/:id returns.
  • data.customerExternalId is the externalId you registered the customer under, or null on a test event.
  • id identifies the event. Treat it as an opaque string.
  • createdAt is when this request was sent, not when the shipment changed.

Current state, at least once​

  • The payload is the shipment's current state when it is sent, not a diff. Several quick changes can arrive as one event.
  • Delivery is at-least-once, and events can arrive out of order. Use data.shipment.updatedAt to ignore a state older than the one you hold, and id to de-duplicate.
  • A redelivery of the same state reuses the same id. A later change gets a new id.

Verify the signature​

  1. Take the raw request body bytes. Verify before you parse the JSON: a re-serialized body may not match.
  2. Split CC-Signature into t and v1.
  3. Compute HMAC-SHA256(secret, "<t>.<raw body>") as lowercase hex. The key is your whole webhook secret, ccwh_ prefix included.
  4. Compare it with v1 in constant time.
  5. Reject the request if t is more than 5 minutes from your clock.

The secret is ccwh_ followed by base58. To get the raw body: express.raw({ type: 'application/json' }) in Express, request.get_data() in Flask, request.body in Django.

Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_S = 300

export function verifyWebhook(rawBody, header, secret) {
const parts = Object.fromEntries(
(header ?? '').split(',').map((p) => p.trim().split('='))
)
const { t, v1 } = parts
if (!/^\d+$/.test(t ?? '') || !v1) return false
if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_S) return false
const expected = Buffer.from(
createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex')
)
const given = Buffer.from(v1)
return given.length === expected.length && timingSafeEqual(given, expected)
}

Python:

import hashlib
import hmac
import time

TOLERANCE_S = 300

def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or not v1:
return False
if abs(time.time() - int(t)) > TOLERANCE_S:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)

Responses and retries​

Any 2xx within 10 seconds is success. Your response body is ignored.

Anything else is a failure: another status, a timeout, a connection error, or a redirect. Redirects are never followed. A failed event is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h: 8 attempts over about 45 hours. After that the event is dropped. A further change to the same shipment queues a fresh event.

Respond quickly and process the event asynchronously.

Signing secret​

The secret is shown once: when you create the webhook, and when you roll it. Rolling takes effect immediately: the next delivery is signed with the new secret, and the old one no longer verifies. A delivery you reject while you deploy the new secret is retried on the schedule above.

Partner console​

Manage your keys and webhook, and see your numbers.

EnvironmentURL
Productionpartner.collectorcrypt.com
Devnetdev-partner.collectorcrypt.com

Sign in​

Sign in with a regular CollectorCrypt account, the same login as collectorcrypt.com: email, Google or wallet. Until the account is linked to your partner account, the console shows its wallet address. Send that address to support@collectorcrypt.com and we link it. An account belongs to one partner only. To remove someone's access, ask CollectorCrypt; it takes effect on their next request.

Keys​

The list shows each key's prefix, name, scopes, status and when it was last used. The console never shows an existing key's secret.

  • Create key mints a key with the scopes you tick, and shows its secret once. The console offers the scopes granted to your account, all ticked by default; give each key only what it needs. Keys never expire. A new account has every scope except buyback, which CollectorCrypt grants on request.
  • Replace mints a new key with the same scopes, minus any no longer granted to your account, and shows its secret once. The old key keeps working until you revoke it, so deploy the new key first, then revoke the old one.
  • Revoke takes effect on the next request.
  • You cannot change a key's scopes, or replace a revoked key. Create a new key with the scopes you need instead.

A key is still a server secret. Put a new one straight into your server's secret store; the console cannot show it again.

Webhook​

Set the URL, enable or disable it, roll the signing secret, send a test ping or a test event, see the result of the last delivery, or remove the webhook. Removing it drops any queued events. See Webhooks.

Stats​

Your number of customers, your shipments by status, and the shipments created in the last 30 days.

Errors​

Every error body has the same three fields:

{ "statusCode": 404, "code": "CUSTOMER_UNKNOWN", "message": "No customer with that externalId" }

Branch on code. message is for humans and may change.

StatuscodeMeaning
400VALIDATION_FAILEDThe body is malformed, a field is missing or invalid, or the route does not apply to this customer (for example signatures for an EVM customer).
400CONTACT_PHONE_REQUIREDThe address has no phone number.
400CONTACT_EMAIL_REQUIREDThe address has no email.
400DESTINATION_RESTRICTEDWe do not ship to that country or region.
400WALLET_NOT_SUPPORTEDA wallet that cannot be registered: a Solana smart-contract wallet, or a CollectorCrypt system wallet. On buybacks: a wallet that cannot request buybacks through the API.
400CARD_NOT_REDEEMABLEA card is not in a redeemable state (for example already burned).
400MIXED_CHAINSCards from more than one chain in one shipment.
400CHAIN_NOT_SUPPORTEDThe cards' chain has no EVM payment token configured. EVM payment is taken on Base and Robinhood Chain.
400INSUFFICIENT_BALANCEThe paying wallet cannot cover the fee.
401UNAUTHORIZEDKey missing, invalid or revoked.
403SCOPE_MISSINGThe key does not carry this route's scope.
403RAIL_NOT_ENABLEDYour account is not enabled for this payment rail.
403VAULT_NOT_ENABLEDNo customer is linked to your account. Contact support.
403BATCH_NOT_ISSUEDSolana: these are not the transactions CollectorCrypt built for this shipment, they mix two batches, or the batch is older than 15 minutes. Call rebuild.
403BATCH_INCOMPLETESolana: a transaction is missing or duplicated.
404CUSTOMER_UNKNOWNNo such customer in your namespace.
404ADDRESS_NOT_FOUNDNo such address for this customer.
404SHIPMENT_NOT_FOUNDNo such shipment, or inbound shipment, for this customer.
404ROUTE_NOT_FOUNDNo such route under /partner/v1. Check the method and path.
404CARDS_NOT_FOUNDA card does not exist, or this customer does not hold it.
409CUSTOMER_WALLET_CONFLICTThis externalId is registered to a different wallet.
409WALLET_ALREADY_REGISTEREDThis wallet is registered under another of your externalIds.
409WALLET_AMBIGUOUSThe EVM wallet matches more than one CollectorCrypt account. Contact support.
409CUSTOMER_WALLET_UNLINKEDThe account this customer was linked to no longer holds the wallet. Contact support.
409SHIPMENT_NOT_MODIFIABLEThe shipment is past the state this action needs, or cancelled.
409DELIST_FAILEDSolana: releasing a card from an external marketplace listing failed. Nothing was burned.
409TOTAL_CHANGEDSwap-paid: the shipping total moved since the estimate you quoted. Estimate again and retry. EVM remaining calls: the payment no longer matches the one frozen on the shipment. Contact support.
500INTERNALUnexpected error. Retry; contact support if it persists.
503UNAVAILABLETemporarily unavailable. Retry with backoff.

Anything you did not create looks like it does not exist: another partner's customer, address or shipment returns the same 404 as a random id.

Need help? support@collectorcrypt.com