/api/v1/mystery/redemption/prepare cards:redeemStarts a physical redemption: stores the address, locks in the cheapest shipping rate, and returns the transaction the END USER sends from the wallet holding the card. That transaction flags the card for redemption — the card isn’t burned until the item ships, so nothing leaves the wallet yet. Only the holder can send it (rip.fun can’t do this one for them). Supply purchase_id OR token_id (token_id alone works for cards you distributed yourself). rip.fun runs no KYC/AML — screening your end user is your responsibility.
POST /api/v1/mystery/redemption/prepare money These inputs are shared across all docs pages — an id entered here carries over.
{
"shipping_address": {
"name": "Demo Buyer",
"street1": "1 Market St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"idempotency_key": "demo-redeem-0-single"
}Not run yet — press Run to make a live call against https://service.rip.fun (through this demo's server-side proxy; the API key never reaches the browser).
curl -X POST 'https://service.rip.fun/api/v1/mystery/redemption/prepare' \
-H 'X-API-Key: rip_…' \
-H 'Content-Type: application/json' \
-d '{"shipping_address":{"name":"Demo Buyer","street1":"1 Market St","city":"San Francisco","state":"CA","zip":"94105","country":"US"},"idempotency_key":"demo-redeem-0-single"}' | Field | Type | Required | Description |
|---|---|---|---|
purchase_id | number | — | The fulfilled purchase holding the item (supply this OR token_id) |
token_id | string | — | On-chain token id (token-first; supply this OR purchase_id; also disambiguates a multi-item purchase) |
item_type | string | — | "CARD" | "GRADED_CARD" | "PACKET" | "SEALED_PRODUCT" — disambiguates a token number that exists as more than one asset (raw Card #N vs GradedCard slab #N) |
idempotency_key | string | — | Replay-safe; an Idempotency-Key header is also accepted |
shipping_address.name | string | yes | Recipient full name |
shipping_address.street1 | string | yes | Street line 1 (`street2` optional) |
shipping_address.city | string | yes | City |
shipping_address.state | string | — | State / region |
shipping_address.zip | string | yes | Postal code |
shipping_address.country | string | yes | ISO country code, e.g. `US` (`phone`, `email` optional) |
data)| Field | Description |
|---|---|
redemption_id / status | PREPARED — the transaction is ready to send |
shipping_quote | Snapshotted cheapest rate (same shape as /quote) |
expires_at | how long the returned transaction stays valid (default 24 h); EXPIRED is retryable with a new idempotency_key |
unsigned.chain_id / unsigned.calls[] | the transaction the END USER sends from the wallet holding the card — flags it for redemption; the card burns when the item ships |
| Status | Code | When |
|---|---|---|
| 400 | purchase_or_token_required | neither purchase_id nor token_id supplied |
| 409 | not_fulfilled | purchase path: purchase not revealed yet |
| 409 | not_burnable | token unindexed / burned / not in a redeemable state, or already queued |
| 409 | not_owner | token left the holder wallet — the holder must be the burn signer |
| 404 | token_not_found | token-first: no rip.fun item for that token |
| 409 | ambiguous_token | token-first: id is both a raw and a graded card — pass item_type ("CARD" or "GRADED_CARD") or use purchase_id |
| 409 | item_type_mismatch | item_type contradicts what the token actually is |
| 409 | redemption_exists | re-preparing after the burn already started |
| 400 | invalid_address | Shippo cannot validate the address |
See Errors for the response envelope and the full code list.