Gacha API

Add mystery packs to your platform. List tiers and their published odds, sell a pack, reveal the pull, then let the user cash out instantly or ship the card to their door, all against real graded inventory priced by the Card Data API. Every action is attributed to your partner key.

The Gacha API is rip.fun's own pack business exposed as an API. You design the packs and bring the players; rip.fun owns the cards, runs the reveal, funds the buyback and ships the physical card when a player asks for it. You earn a share of the net revenue you generate.

Powered: Every route runs on rip.fun's production service: the same reveal engine, Base settlement and pricing that back the rip.fun marketplace and the Card Data API. There is no inventory system, wallet or chain integration to stand up on your side.
Sourced: rip.fun buys and grades the cards that fill the packs. That is why the published odds and average_item_value are inventory-derived rather than a synthetic table, and why a pull is priced against the same market data the Card Data API serves.
Warehoused: Cards sit in rip.fun's own vault and stay insured the whole time they're in it. The physical card doesn't move until someone redeems it; on-chain, the player holds the token for one specific card. Sell it back and the card returns to the pool it came from, paid for out of the buyback float the pack price already funded. Redeem it and the vault buys a live shipping label, ships the card and burns the token on dispatch.

Trusted by Phygitals Traded rip.fun

Three calls to a working pack

Prepare the transactions, the end-user sends them from their own wallet, and you record the hash. You poll for the reveal — no funds to hold and no chain awareness beyond passing calldata through.

// 1. Show the packs you're selling
const { data } = await cardos.gacha.catalog.list({ game: 'pokemon' });

// 2. Hand the transactions to the user's wallet
const { data: prep } = await cardos.gacha.purchase.prepare({
  wallet_address: userWallet,
  tier_id: data.tiers[0].tier_id
});
const txHash = await userWallet.sendCalls(prep.calls);

// 3. Record it, then poll (or take the purchase.fulfilled webhook)
const purchase = await cardos.gacha.purchase.submit({ transaction_hash: txHash });

That is the whole integration for a working gacha loop. Everything below is the surface you grow into: buyback, physical redemption, and your revenue share.

Base URLs

Environment	Origin	Notes
Sandbox (staging)	`https://staging-service.rip.fun`	Base Sepolia, which is what the "Try it" runners in these docs call
Production	`https://api.getcardos.com`	Base mainnet. Alias of `https://service.rip.fun` — both origins serve the same API; older examples use the rip.fun name and either works.

All endpoints live under the /api/v1 base path and require an X-API-Key.

Wire conventions

Money is always a string, never a JSON number. Fields suffixed _micros (or named price/amount/balance bare) are integer USDC micros as strings — "12500000" = 12.5 USDC. Fields suffixed _usdc are the same value as a decimal string for display. Reveal items' value_usd is a USD decimal string from market pricing (not micros). Never parse any of them into a float you do arithmetic on.
Ids: tier_id, purchase_id and other row ids are JSON numbers (integers). token_id, request_id and card_id are strings. If any docs page shows tier_id quoted, that's a docs bug — the wire type is a number.
Timestamps are ISO-8601 strings; addresses are 0x-hex strings (lowercased on the way in).

Prefer codegen? The full surface is published as an OpenAPI spec: gacha-openapi.yaml.

Rate limits

The Gacha API is limited to 240 requests per minute per key — a separate, lower ceiling than the Card Data API's 300/min. On top of the per-minute 429, the server bounds concurrent in-flight requests with global semaphores shared with the Instant Pack API — 24 reads, 5 purchases, 10 writes, 10 wallet reads. A short burst beyond those queues briefly (up to ~500ms) for a free slot; only a sustained overload sheds with a 503 and Retry-After: 1. Size your client for sequential calls with modest parallelism and honor Retry-After on both statuses.

Custody — two purchase models

Self-custody (default). The end-user holds their own funds and their own cards. The API returns the transactions to send (prepare), the end-user sends them from their own wallet, and you record the transaction (submit). CardOS never takes custody of either — which is also why only the card's own holder can sell it back.

Custodial. If your users don't have wallets, fund a per-user CardOS credits wallet (deposit, then balance) and open packs server-side with a single POST /mystery/purchase — no signing, no browser wallet, one idempotent call per pull. The pulled cards are minted to a CardOS-managed wallet keyed to your external_user_id.

Partner accounts settle on the TIER model: you sell rip.fun tiers, and sell-backs and revenue share settle through /sellback, /revenue and /payouts — you earn a share of net revenue, paid in USDC, and are never billed per item. (A legacy POOL model exists for a few grandfathered partners who hold their own inventory; it is not offered to new partners, and its endpoints answer 403 not_pool_partner/not_tier_partner across models. Which model your key is on is returned by GET /api/v1/info as mystery_partner.billing_model.)

What you can build on it

Tiers & odds Published pull rates and expected value per tier, the numbers you show players. Purchases Hand the transactions to the user's wallet and record the hash. Instant packs A sibling product on the same key: buy and open a real booster pack in one transaction. Instant buyback The holder sells the pull straight back to the pool, paid on the spot in USDC. Physical redemption Ship the real card: live shipping quotes, the holder’s own signature, tracked fulfillment. Screening the end user stays with you — CardOS runs no KYC/AML. Live feeds Recent pulls and top winners, the social proof that makes a shop feel alive. Webhooks Signed delivery for fulfillment, buyback, payout and redemption state changes.

Living documentation

Every endpoint page embeds a live runner: tweak the request inputs, press Run, and see the real staging response (status + latency), plus a ready-to-copy curl snippet that tracks your inputs. The partner API key stays on this demo's server, and the browser only ever talks to a whitelisted proxy.

To see the whole product (connect a wallet, buy a pack, reveal the card, sell it back or redeem it physically) open the storefront demo.

Quick start

Get a partner API key (see Authentication).
List tiers and odds to render your shop.
Purchase: prepare → user signs → submit.
Or sell an instant pack on the same key: buy and open a real booster pack in one call, with the cards delivered seconds later.
Poll purchase status (or use webhooks) until FULFILLED, then show the revealed items.
Offer a buyback or a physical redemption.

The three multi-party sequences (who signs what, which webhooks fire) are spelled out in End-to-end flows.

Get testnet funds (Base Sepolia)

To run the sandbox flows (buy a pack, sell it back, redeem it) your test wallet needs a little Base Sepolia ETH for gas plus USDC to pay for packs. Staging's payment token is Circle's native Base Sepolia USDC at 0x036CbD53842c5426634e7929541eC2318f3dCF7e, the same token Circle's faucet dispenses.

USDC. Circle faucet: select Base Sepolia; ~20 USDC per address every 2 hours, no account needed.
Gas ETH. Coinbase Developer Platform faucet (up to 0.1 ETH per 24h; also dispenses USDC), or Alchemy's Base Sepolia faucet (free account, 1 claim per 24h).
Fuller list: the Base docs network-faucets page.

Tier 1 on staging costs $1 USDC, so a single Circle claim covers ~20 test purchases.

Want cards sourced just for you?

The catalog above is the standard inventory. RIP.FUN will also buy and grade to your brief, be that a chase list you pick, sealed product for a launch, or a one-off drop, and hold it all in our own vault, insured until the day it ships. Contact us →