{"openapi":"3.1.0","info":{"title":"Relic Public API","version":"1.0.0","description":"Read access to Relic drops, prizes, odds, expected value, and creators. Write actions (create drop, pull, sell-back, stock, withdraw) are non-custodial — authorized by the caller's own wallet signature or an on-chain transfer they sign — and are wrapped by the @relic/sdk TypeScript client (see /developers). No API key required."},"servers":[{"url":"https://relicdrops.com/api/v1"}],"paths":{"/drops":{"get":{"summary":"List drops","parameters":[{"name":"chain","in":"query","schema":{"type":"string","enum":["solana","base"]}},{"name":"inStock","in":"query","schema":{"type":"boolean"}},{"name":"prizeKind","in":"query","schema":{"type":"string","enum":["memecoin","nft","collectible","mixed","empty"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","ev","price"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"List of drop summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropList"}}}}}},"post":{"summary":"Create a drop (non-custodial — signed by the creator wallet)","description":"Full parity with the web creator. Body: name, description, thumbnail (cover image URL), priceUsdc, odds (per-rarity weights), sellBackRate, minByTier, mystery, endsAt, gate, and tokenPrizes (memecoin — each { rarity, mint, symbol, decimals, amountBase, image? }; logo auto-resolves if image omitted) or collectibles via /drops/:id/inventory. Plus creatorWallet + authMessage/authSignature over 'Relic: create-drop @ <ms>'. Token drops start as draft → fund via /stock → publish via /status.","responses":{"200":{"description":"Created drop"},"401":{"description":"Missing/invalid signature"}}}},"/drops/{idOrSlug}/status":{"post":{"summary":"Set a drop's status (publish/pause/end) — owner, signed","description":"Body: { wallet, status: 'live'|'paused'|'ended', authMessage, authSignature } over 'Relic: manage drop <id> @ <ms>'.","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated status"},"401":{"description":"Signature required"},"402":{"description":"Under-collateralized (going live)"},"403":{"description":"Not the owner"}}}},"/drops/{idOrSlug}/inventory":{"post":{"summary":"Stock collectible items (owner/approved supplier, signed)","description":"Body: { wallet, items:[{name,rarity,insuredValue,...}], authMessage, authSignature, signature? } — signed over 'Relic: stock @ <ms>'. NFT prizes also pass the deposit tx signature.","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Items added"},"403":{"description":"Signature required / not allowed"}}}},"/drops/{idOrSlug}/pull":{"post":{"summary":"Pull (pay price×n USDC, signed by the player)","description":"Body: { wallet, n?, signature (your USDC transfer), commitId?, clientSeed?, recipient? }. Returns prizes + fairness proof; failures refund in full. Pass `recipient` to GIFT the pull (you fund it; the token prize goes to recipient's wallet) — token-prize drops only; loop it for a gacha airdrop.","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pull results"},"402":{"description":"Payment unverified"},"409":{"description":"Not pullable / replay"}}}},"/pulls/{id}/resolve":{"post":{"summary":"Sell back or keep a revealed prize","description":"Body: { disposition: 'sold_back'|'shipped', message, signature } over 'Relic: resolve pull <id> @ <ms>'.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resolved"},"401":{"description":"Signature required"},"409":{"description":"Already resolved"}}}},"/drops/{idOrSlug}/collateral":{"get":{"summary":"Public collateral position + ledger","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collateral status"}}},"post":{"summary":"Post collateral (owner only; USDC transfer you sign)","description":"Body: { wallet, amount, signature }.","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated collateral"},"402":{"description":"Transfer unverified"},"403":{"description":"Not the owner"}}}},"/drops/{idOrSlug}/stock":{"post":{"summary":"Stock a token prize (deposit the token into escrow, signed)","description":"Body: { wallet, signature, mint, symbol, decimals, rarity, amountBase, depositBase, itemId? } — or ladder mode { winners | priceUsd }.","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Inventory updated"},"402":{"description":"Deposit unverified"},"403":{"description":"Not an allowed supplier"}}}},"/creators/{wallet}/withdraw":{"post":{"summary":"Withdraw accrued earnings (signed authorization)","description":"Body: { message, signature } over 'Relic: withdraw <wallet> @ <ms>'.","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Withdrawal recorded"},"401":{"description":"Signature required"},"409":{"description":"Nothing to withdraw"}}}},"/profile/shipping":{"post":{"summary":"Read your saved shipping address (signed; PII, owner-only)","description":"Body: { wallet, message, signature } over 'Relic: manage shipping address <wallet> @ <ms>'.","responses":{"200":{"description":"Saved profile (or null)"},"401":{"description":"Signature required"}}},"put":{"summary":"Create/update your shipping address — required to redeem RWA prizes","description":"Body: { wallet, name, address, country, email?, message, signature }.","responses":{"200":{"description":"Saved"},"401":{"description":"Signature required"}}}},"/fairness/commit":{"post":{"summary":"Get a provably-fair commit (step 1 of a pull)","responses":{"200":{"description":"{ commitId, serverSeedHash }"}}}},"/drops/{idOrSlug}":{"get":{"summary":"Get a drop (by id or slug), with its prize pool","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Drop detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropDetail"}}}},"404":{"description":"Drop not found"}}}},"/drops/{idOrSlug}/quote":{"get":{"summary":"Prepare a pull — payment instructions for n pulls","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Treasury, USDC mint, total price, max pulls/tx"},"404":{"description":"Drop not found"}}}},"/creators/{wallet}":{"get":{"summary":"Get a creator's public profile + live drops","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Creator profile"}}}},"/health":{"get":{"summary":"Liveness + version","responses":{"200":{"description":"ok"}}}}},"components":{"schemas":{"Drop":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"chain":{"type":"string","enum":["solana","base"]},"url":{"type":"string"},"image":{"type":["string","null"]},"mystery":{"type":"boolean"},"pricePerPull":{"type":"number"},"currency":{"type":"string"},"expectedValue":{"type":["number","null"],"description":"Average prize value per pull (USD); null if not yet priced."},"odds":{"type":"object","additionalProperties":{"type":"number"},"description":"Normalized % per live rarity tier."},"tiers":{"type":"array","items":{"type":"string"}},"buybackRate":{"type":"number","description":"Instant sell-back as a fraction of insured value."},"collateralBacked":{"type":"boolean"},"collateralPct":{"type":"number"},"itemsAvailable":{"type":"integer"},"itemsTotal":{"type":"integer"},"outOfStock":{"type":"boolean"},"prizeKind":{"type":"string"},"holderGate":{"type":["object","null"]},"creator":{"type":"object"},"createdAt":{"type":"integer"},"endsAt":{"type":["integer","null"]}}},"DropList":{"type":"object","properties":{"ok":{"type":"boolean"},"drops":{"type":"array","items":{"$ref":"#/components/schemas/Drop"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"DropDetail":{"type":"object","properties":{"ok":{"type":"boolean"},"drop":{"allOf":[{"$ref":"#/components/schemas/Drop"},{"type":"object","properties":{"description":{"type":"string"},"prizes":{"type":"array","items":{"type":"object","properties":{"rarity":{"type":"string"},"type":{"type":"string","enum":["collectible","token"]},"value":{"type":["number","null"]},"available":{"type":"boolean"},"isRwa":{"type":"boolean"},"name":{"type":["string","null"]},"image":{"type":["string","null"]},"nftMint":{"type":["string","null"]},"token":{"type":["object","null"]}}}}}}]}}}}}}