Prepare purchase

POST /api/v1/instant/purchase/prepare packs:purchase

Purchase step 1. Returns the USDC-approve and buy-and-open transactions for the END USER to send from their own wallet. CardOS never touches their funds, and the cards deliver straight to that wallet once the VRF settles. Creates nothing.

Try it POST /api/v1/instant/purchase/prepare write

These inputs are shared across all docs pages, so an id entered here carries over.

request body
object · 2 keys 
{
  "wallet_address": "0x0000000000000000000000000000000000000000",
  "packet_type_id": 14
}
response

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).

tracks the inputs above
curl -X POST 'https://service.rip.fun/api/v1/instant/purchase/prepare' \
  -H 'X-API-Key: rip_…' \
  -H 'Content-Type: application/json' \
  -d '{"wallet_address":"0x0000000000000000000000000000000000000000","packet_type_id":14}'

Request fields

FieldTypeRequiredDescription
wallet_addressstringyesEnd-user wallet that will sign + pay
packet_type_idnumberyesPacket type to buy, from GET /instant/catalog
max_price_usdcstring—Price cap; defaults to the current pack price

Response fields (data)

FieldDescription
chain_id / payment_token / contractChain + USDC + store contract addresses
packet_type_idEchoed packet type the calls purchase
price / price_usdcApproval amount (USDC micros string + decimal display)
calls[]{to, data, description}: approve USDC, then the buy-and-open (purchaseInstantOpenFor) call

Errors

StatusCodeWhen
400invalid_packet_typepacket_type_id is not a purchasable instant pack
400invalid_wallet_addresswallet_address is not a valid 0x-prefixed EVM address
409sold_outno card bundles available for that packet type right now
409max_price_exceededthe current pack price exceeds your max_price_usdc
503instant_disabledinstant pack purchasing temporarily disabled

See Errors for the response envelope and the full code list.

Flow

  1. Partner: POST /instant/purchase/prepare with the user’s wallet_address + packet_type_id
  2. End user: sends calls[0] (USDC approve, skip if allowance already covers it) then calls[1] (buy-and-open) from their own wallet
  3. Partner: POST /instant/purchase/submit with the tx hash to link it
  4. CardOS: correlates the on-chain events; Chainlink VRF delivers the bundle to the user’s wallet — poll GET /instant/purchase/:id until FULFILLED (or use the instant_purchase.* webhooks)