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 noX-CC-Customerheader. - Your vault inventory is account-level:
GET /vault-itemslists the items CollectorCrypt holds in its vault for your account, with noexternalId. 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
| Environment | Base URL |
|---|---|
| Production | https://api.collectorcrypt.com/partner/v1 |
| Devnet | https://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.
| Scope | Routes |
|---|---|
customers:provision | POST /customers, GET /customers/:externalId |
shipping-address | /customers/:externalId/addresses/* |
redeem | estimate, create, burn, signatures, rebuild |
outbound-shipment | GET /customers/:externalId/shipments[/:id] |
inbound-shipment | /customers/:externalId/inbound-shipments/* |
vault-items | GET /vault-items |
buyback | POST /customers/:externalId/buybacks. Granted to your account on request; see Buybacks. |
Payment rails
Your account is enabled for one or more rails:
| Rail | Customer | Who pays | Section |
|---|---|---|---|
| Solana | A Solana wallet | The customer, or your own wallet, in Solana USDC inside the burn transaction | Solana redemptions |
| EVM | An EVM wallet | The customer's wallet, on the card's chain (USDC on Base, USDG on Robinhood), with a pay() call next to the burn | EVM redemptions |
| Swap | A Solana wallet | Your swap wallet, in Solana USDC, from a swap your customer signs in your token. Optional, on any Solana shipment | Paying with a swap |
The flow
- Register the customer —
POST /customerswith yourexternalIdand their wallet. - Save an address —
POST /customers/:externalId/addresses. - Estimate (optional) —
POST /customers/:externalId/shipments/estimate. - Create the shipment —
POST /customers/:externalId/shipments. Returns the transactions to sign, or the EVM calls to send. - Your customer signs, and you submit what they signed.
- Track —
GET /customers/:externalId/shipments/:iduntil it isPending, thenShippedandDelivered.
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
| Limit | Value |
|---|---|
Shipments per page (pageSize) | 100 |
Vault items per page (pageSize) | 100 |
| Wallets per customer | 1 (Solana or EVM) |
externalId length | 1–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/jsonand a non-emptyUser-Agent. - Every error has a string
code:{ "statusCode": 404, "code": "CUSTOMER_UNKNOWN", "message": "..." }. Branch oncode, not onmessage. See Errors. - Cost fields are decimal strings in USD.
- Card identifiers are the same
nftAddressvalues the Shipping API uses: the base58 asset address on Solana,<chain>-<contract>-<tokenId>on EVM. See Card identifiers.
Customers
POST /customers — scope customers:provision.
| Field | Type | Required | Notes |
|---|---|---|---|
externalId | string | yes | Your id for this customer, 1–160 characters. It goes in every other URL. |
walletChain | solana | evm | yes | |
wallet | string | yes | Base58 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
externalIdis bound to one wallet for good. Posting it with a different wallet returns409 CUSTOMER_WALLET_CONFLICT. Register the new wallet under a newexternalId. - One wallet, one customer. Registering a wallet you already registered under another
externalIdreturns409 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
buybackscope, 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.
| Field | Type | Required | Notes |
|---|---|---|---|
fullName | string | yes | ≤ 128 |
streetAddress | string | yes | ≤ 256 |
apartment | string | no | ≤ 128 |
city | string | yes | ≤ 128 |
state | string | yes | A code or a name; stored as the subdivision name, so "CA" becomes "California". Send an empty string for a country with no subdivisions. |
zip | string | no | Needed for correct US rates. ≤ 32 |
country | string | yes | ISO 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). |
phoneNumber | string | yes | The carrier's contact. ≤ 32 |
email | string | yes | The 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.
| Route | Notes |
|---|---|
GET /customers/:externalId/addresses | { "items": [ … ] }, newest first. |
GET /customers/:externalId/addresses/:id | One address, or 404 ADDRESS_NOT_FOUND. |
PATCH /customers/:externalId/addresses/:id | Any subset of the fields above. The result must still have a phone and an email. |
DELETE /customers/:externalId/addresses/:id | 204. 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.
| Field | Type | Required |
|---|---|---|
nftAddresses | string[] | yes, at least 1 |
addressId | string | yes |
payCustomsDuties | boolean | no |
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.
| Field | Type | Required | Notes |
|---|---|---|---|
nftAddresses | string[] | yes | Cards held by the customer's Solana wallet. |
addressId | string | yes | |
payCustomsDuties | boolean | no | |
payerWallet | string | no | A Solana wallet of yours that pays the fee instead of your customer. It must sign too — see Paying for your customer. |
relayBurn | boolean | no | true 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—nullunless you sentrelayBurn: trueand 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,payCustomsDutiesorpayerWalletcreates a new shipment.totalCostis the order's total;amountDueis what is still owed. Both are decimal strings.
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" }
]
status | Meaning |
|---|---|
linked | Confirmed, verified as this shipment's, and recorded. |
pending | Not confirmed yet. Report it again in a few seconds. |
rejected | Not 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>"]
}
}
- Your customer signs every transaction, in one wallet prompt. Submit them all through burn. Tx A landing pays the shipment and records the consent.
- Ask the partner to burn. For RipMart, call
redeem.executein the RipMart SDK with the shipment id, your customer's wallet andpartnerBurns.items, unchanged and in order. The partner checks that list against the consent on chain. - The partner burns each card in its own transaction, carrying the memo
cc shipment: <id>. CollectorCrypt links each burn as it lands. The shipment reachesPendingonce 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 sameitemsandmerkleRoot.- rebuild — send
relayBurn: trueagain. It returns Tx A while the consent has not landed; once it has, Tx A is left out. GET /customers/:externalId/shipments/:idre-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.
| Field | Type | Notes |
|---|---|---|
swapWallet | string | Your wallet that pays CollectorCrypt the USDC. It signs Tx A and pays its network fee. |
swapMint | string | The token your customer pays you in. SPL Token or Token-2022. |
swapAmount | string | Your customer's side, in swapMint base units. Your rate. |
expectedTotal | string | The 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
swapAmountofswapMintto your swap wallet; - your swap wallet pays exactly
totalCostUSDC to CollectorCrypt; - the partner consent, when you sent
relayBurn: trueand 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.
- Check Tx A before your swap wallet signs it: it spends your USDC.
- Sign Tx A with your swap wallet. Your customer signs every transaction, in one wallet prompt.
- 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.
| Chain | Token | Production | Devnet |
|---|---|---|---|
| Base | USDC | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | 0x036cbd53842c5426634e7929541ec2318f3dcf7e |
| Robinhood Chain | USDG | 0x5fc5360d0400a0fd4f2af552add042d716f1d168 | 0x7e955252e15c84f5768b83c41a71f9eba181802f |
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
batchBurncarries the shipment id as its memo, and so doespay(payment.memo). That is what ties them to this shipment. approvegrants exactly the amount due, never an unlimited allowance.amountRawis in the token's 6-decimal units (5990000is 5.99). The amount is fixed when the shipment is created.chainIdis the cards' chain. The example is a Base card; a Robinhood card returns"chain": "robinhood",chainId4663(devnet46630), and USDG astoken.paymentrepeatsevmCallBundle.payment.evmTransactionslists the same burns: oneburnTxsentry perbatchBurn, in the same order, and thetokenIdsthey burn. With anevmCallBundle, they are already in itscalls; do not send them twice.burnTxs[].gasis a gas limit for thatbatchBurn: CollectorCrypt's estimate plus 30%.evmCallBundle.callscarry none. A group of 50 cards or fewer also hasburnTx, the same call as its onlyburnTxsentry; readburnTxs.
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.callsas onewallet_sendCallsbatch, withatomicRequired: truewhere 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. EverybatchBurncomes beforepay; 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" }]
status | Meaning |
|---|---|
confirmed | Mined, and it burned this shipment's cards with this shipment's memo. Recorded. |
pending | Not 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. |
rejected | Reverted, 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.
| Shipment | evmCallBundle | evmTransactions |
|---|---|---|
| Cards left, not paid | approve, one batchBurn per 50 cards left, pay | The same burns |
| Cards left, paid | null, and so is payment | The burns: send each burnTxs entry, in order |
| Every card burned, not paid | approve, 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
numberOfCardsare strings. paymentis the frozen EVM payment intent (chain,token,spender,amountRaw,memo,paid) on the EVM rail, andnullotherwise. It lets you recover what is owed if you lost the create response.customIdis the order number CollectorCrypt's warehouse and support use.
List shipments
GET /customers/:externalId/shipments — scope outbound-shipment. Newest first.
| Query | Notes |
|---|---|
status | Comma-separated statuses, e.g. Pending,Processing,Shipped. |
createdFrom, createdTo | ISO 8601. |
pageSize | Up to 100. Default 100. |
cursor | Leave 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.
totalcounts every shipment that matches the filters.pageis always1.
Statuses
| Status | Meaning |
|---|---|
Created | Created; not yet paid or burned. |
PaymentPending | Burn recorded, payment not yet credited (EVM). |
PaymentReceived | Paid, burn not yet recorded. |
Pending | Paid and burned. Accepted by the warehouse. |
Processing | Being packed. |
Shipped | Handed to the carrier. trackingIds are set. |
Delivered | Delivered. |
ActionRequired | Needs CollectorCrypt's attention — email support with the customId. |
Cancelled | Cancelled. |
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:
- Create the shipment. Note its
idandshipTo. - Add the cert numbers of the cards in the box.
- Write the shipment
idon the box and send it toshipTo. - Add the tracking number. The shipment becomes
Shipped. - 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.
| Field | Type | Required | Notes |
|---|---|---|---|
numberOfCards | integer | yes | 1–100000. How many cards the box holds. |
description | string | no | Up to 160 characters. |
valueOfBox | number | no | The 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"
}
| Field | Type | Notes |
|---|---|---|
id | string | CollectorCrypt's id for the shipment. Write it on the box. |
status | string | See Inbound statuses. |
description | string | null | |
numberOfCards | integer | The count you declared. |
numberOfCardsReceived | integer | null | The count the vault received. |
valueOfBox | string | The declared value in USD, to the cent. |
trackingId, trackingUrl | string | null | The last tracking number added, and its carrier link. |
shipTo | string[] | The address lines to send the box to. |
parcels | object[] | One per tracking number added: trackingNumber, carrierCode, status, statusAt, deliveredAt. |
createdAt, updatedAt | string | ISO 8601. |
Add cert numbers
POST /customers/:externalId/inbound-shipments/:id/certs — scope inbound-shipment.
| Field | Type | Required | Notes |
|---|---|---|---|
certIds | string[] | yes | 1–2000 cert numbers. Letters and digits only, up to 32 characters each. Repeats are dropped. |
gradingCompany | string | no | A 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,numberOfCardsandvalueOfBoxcan change while the shipment isDraft,NeworShipped.trackingIdcan be added in the same states. It makes the shipmentShippedand adds a parcel. Add one per box: earlier numbers stay inparcels.- Anything else returns
409 SHIPMENT_NOT_MODIFIABLE. An empty body returns400 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.
| Query | Notes |
|---|---|
status | Comma-separated statuses. Leave it out for every status. |
pageSize | 1–100. Default 100. |
cursor | Leave 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
status | Meaning |
|---|---|
Draft | Started on collectorcrypt.com and not submitted. v1 never creates one. |
New | Created. No tracking yet. |
Shipped | A tracking number was added. |
Received | The vault has the box. |
Processing | The vault is scanning the items in. |
AwaitingMint, PartlyMinted, FullyMinted | CollectorCrypt is minting the items it owns. |
Canceled | Cancelled. 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.
| Query | Notes |
|---|---|
search | Matches part of the cert number, card name, set or vault handle. Case is ignored. |
cert | Comma-separated cert numbers, matched exactly. |
status | Comma-separated statuses, e.g. Vaulted,Sent. Leave it out for every status. |
type | Comma-separated item types, e.g. Card,CardRaw. |
gradingCompany | Comma-separated graders, exactly as items return them, e.g. PSA,CGC,Beckett. |
createdFrom, createdTo | ISO 8601, compared with createdAt. Both bounds are included. |
pageSize | 1–100. Default 100. |
cursor | Leave 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
}
| Field | Type | Notes |
|---|---|---|
id | string | CollectorCrypt's id for the item. |
status | string | Expected, Vaulted, Sent or Gone. See below. |
type | string | Card, 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. |
gradingCompany | string | null | The grader, e.g. PSA. |
cert | string | null | The grader's cert number. |
grade | string | null | The grade as the grader labels it, e.g. GEM-MT 10. |
cardName | string | null | The card's name. |
set | string | null | The set's name. |
year | string | null | The card's year. |
cardNumber | string | null | The card's number in its set. |
category | string | null | The game, e.g. Pokemon. |
vaultHandle | string | null | The 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. |
media | object[] | Photos and video, newest first. Can be empty. |
media[].type | string | ImageFront, ImageBack, ImageExtra or Video. |
media[].source | string | Vault: added by CollectorCrypt's vault. Grader: from the grading company. |
media[].url | string | null | The full-size file. |
media[].urlMedium, media[].urlSmall | string | null | Smaller copies of url. |
scannedAt | string | null | ISO 8601. When the item was scanned into the vault. null when no scan is recorded, as for an Expected item. |
createdAt | string | ISO 8601. When CollectorCrypt first recorded the item. |
status | Meaning |
|---|---|
Expected | Registered, not yet received. |
Vaulted | In the vault. |
Sent | Shipped out of the vault. |
Gone | The 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.
| Field | Type | Required | Notes |
|---|---|---|---|
nftAddresses | string[] | yes | 1–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.
code | Meaning |
|---|---|
CARDS_NOT_FOUND | The 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_REDEEMABLE | The 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
requestedagain. - 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:
| Status | code | Meaning |
|---|---|---|
| 400 | WALLET_NOT_SUPPORTED | This wallet cannot request buybacks through the API. |
| 400 | VALIDATION_FAILED | nftAddresses is missing, empty or longer than 200. |
| 409 | CUSTOMER_WALLET_UNLINKED | The 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
type | Sent when |
|---|---|
shipment.updated | A v1 shipment's status or trackingIds change, or you send a test event. |
ping | You 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
idstarts withtest.. Headers and signing are the same as for real events. data.shipmentis a sample, not one of your shipments: itsidistest-shipment, itscustomIdisTEST, itsaddressIdisnulland itsnftAddressesis empty.data.customerExternalIdisnull.ShippedandDeliveredcarry the UPS test tracking number1Z999AA10123456784.- A test event is sent once and never retried; the console shows the result.
Request
POST to your URL, with these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | CollectorCrypt-Webhooks/1 |
CC-Signature | t=<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.shipmentis exactly the objectGET /customers/:externalId/shipments/:idreturns.data.customerExternalIdis theexternalIdyou registered the customer under, ornullon a test event.ididentifies the event. Treat it as an opaque string.createdAtis 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.updatedAtto ignore a state older than the one you hold, andidto de-duplicate. - A redelivery of the same state reuses the same
id. A later change gets a newid.
Verify the signature
- Take the raw request body bytes. Verify before you parse the JSON: a re-serialized body may not match.
- Split
CC-Signatureintotandv1. - Compute
HMAC-SHA256(secret, "<t>.<raw body>")as lowercase hex. The key is your whole webhook secret,ccwh_prefix included. - Compare it with
v1in constant time. - Reject the request if
tis 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.
| Environment | URL |
|---|---|
| Production | partner.collectorcrypt.com |
| Devnet | dev-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.
| Status | code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | The 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). |
| 400 | CONTACT_PHONE_REQUIRED | The address has no phone number. |
| 400 | CONTACT_EMAIL_REQUIRED | The address has no email. |
| 400 | DESTINATION_RESTRICTED | We do not ship to that country or region. |
| 400 | WALLET_NOT_SUPPORTED | A 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. |
| 400 | CARD_NOT_REDEEMABLE | A card is not in a redeemable state (for example already burned). |
| 400 | MIXED_CHAINS | Cards from more than one chain in one shipment. |
| 400 | CHAIN_NOT_SUPPORTED | The cards' chain has no EVM payment token configured. EVM payment is taken on Base and Robinhood Chain. |
| 400 | INSUFFICIENT_BALANCE | The paying wallet cannot cover the fee. |
| 401 | UNAUTHORIZED | Key missing, invalid or revoked. |
| 403 | SCOPE_MISSING | The key does not carry this route's scope. |
| 403 | RAIL_NOT_ENABLED | Your account is not enabled for this payment rail. |
| 403 | VAULT_NOT_ENABLED | No customer is linked to your account. Contact support. |
| 403 | BATCH_NOT_ISSUED | Solana: these are not the transactions CollectorCrypt built for this shipment, they mix two batches, or the batch is older than 15 minutes. Call rebuild. |
| 403 | BATCH_INCOMPLETE | Solana: a transaction is missing or duplicated. |
| 404 | CUSTOMER_UNKNOWN | No such customer in your namespace. |
| 404 | ADDRESS_NOT_FOUND | No such address for this customer. |
| 404 | SHIPMENT_NOT_FOUND | No such shipment, or inbound shipment, for this customer. |
| 404 | ROUTE_NOT_FOUND | No such route under /partner/v1. Check the method and path. |
| 404 | CARDS_NOT_FOUND | A card does not exist, or this customer does not hold it. |
| 409 | CUSTOMER_WALLET_CONFLICT | This externalId is registered to a different wallet. |
| 409 | WALLET_ALREADY_REGISTERED | This wallet is registered under another of your externalIds. |
| 409 | WALLET_AMBIGUOUS | The EVM wallet matches more than one CollectorCrypt account. Contact support. |
| 409 | CUSTOMER_WALLET_UNLINKED | The account this customer was linked to no longer holds the wallet. Contact support. |
| 409 | SHIPMENT_NOT_MODIFIABLE | The shipment is past the state this action needs, or cancelled. |
| 409 | DELIST_FAILED | Solana: releasing a card from an external marketplace listing failed. Nothing was burned. |
| 409 | TOTAL_CHANGED | Swap-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. |
| 500 | INTERNAL | Unexpected error. Retry; contact support if it persists. |
| 503 | UNAVAILABLE | Temporarily 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