{"openapi":"3.1.1","info":{"version":"1.0.0","title":"Renaiss Builder API v2","description":"Builder API v2 for direct-EOA gacha, marketplace and redemption on BNB Smart Chain Testnet (chain 97). Any active, approved builder key can prepare purchases.\n\nBrowse publicly, then prepare and sign actions with the buyer wallet. Gacha history and buyback offers require your builder key; purchases and buybacks also require a wallet action signature. Private shipping data and redemption require a scoped wallet session from a registered partner origin. Wallet sessions are not required for gacha or marketplace. Keep the builder key on your backend."},"servers":[{"url":"/","description":"API root"}],"components":{"securitySchemes":{"walletSession":{"type":"http","scheme":"bearer","description":"Builder-bound EOA wallet session with redeem:read/redeem:write scope"},"builderAuth":{"type":"apiKey","in":"header","name":"x-builder-api-key","description":"Your approved builder API key. Keep it on your backend. Gacha and marketplace writes also require wallet action signatures. Private shipping access requires a separate wallet-session bearer token."}},"schemas":{"GachaV2PullStreamEvent":{"oneOf":[{"type":"object","properties":{"event":{"type":"string","enum":["pull_started"]},"data":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"nonce":{"type":"string"},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string"}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message"]}},"required":["event","data"]},{"type":"object","properties":{"event":{"type":"string","enum":["payment_queued"]},"data":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"nonce":{"type":"string"},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string"}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message"]}},"required":["event","data"]},{"type":"object","properties":{"event":{"type":"string","enum":["payment_submitting"]},"data":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"nonce":{"type":"string"},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string"}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message"]}},"required":["event","data"]},{"type":"object","properties":{"event":{"type":"string","enum":["payment_confirmed"]},"data":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"nonce":{"type":"string"},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string"},"permitFundTxHash":{"type":"string"}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message","permitFundTxHash"]}},"required":["event","data"]},{"type":"object","properties":{"event":{"type":"string","enum":["draws_resolved"]},"data":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"nonce":{"type":"string"},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string"},"permitFundTxHash":{"type":"string"},"packName":{"type":"string"},"status":{"type":"string","enum":["RESOLVED"]},"pulledAt":{"type":["string","null"],"format":"date-time"},"draws":{"type":"array","items":{"type":"object","properties":{"settlementId":{"type":"string"},"tokenId":{"type":"string"},"releaseTxHash":{"type":["string","null"]},"buybackTxHash":{"type":["string","null"]},"collectible":{"type":"object","properties":{"name":{"type":"string"},"frontImageUrl":{"type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"buybackBaseValueInUSD":{"type":"string"},"snapshotBuybackValueInUsdt":{"type":["string","null"]}},"required":["name","frontImageUrl","imageUrl","tier","buybackBaseValueInUSD","snapshotBuybackValueInUsdt"]}},"required":["settlementId","tokenId","releaseTxHash","buybackTxHash","collectible"]}}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message","permitFundTxHash","packName","status","pulledAt","draws"]}},"required":["event","data"]},{"type":"object","properties":{"event":{"type":"string","enum":["pull_failed"]},"data":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"nonce":{"type":"string"},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string"},"code":{"type":"string"},"error":{"type":"string"},"permitFundTxHash":{"type":["string","null"]},"fundingConfirmed":{"type":"boolean"}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message","code","error","permitFundTxHash","fundingConfirmed"]}},"required":["event","data"]}]}},"parameters":{}},"paths":{"/v2/auth/wallet/nonce":{"post":{"tags":["Wallet sessions"],"security":[{"builderAuth":[]}],"summary":"Create an EOA sign-in challenge for this builder","description":"Required for private shipping and redemption; not required for gacha or marketplace. Call through the builder backend. Select an exact origin from this builder's server registration; it supplies the SIWE scheme, domain and URI. Sessions requesting exactly redeem:read and redeem:write return SDK context separately and omit custom Resources from the wallet message. Single redeem scopes and sets including gacha:read keep signed Resources and return no context. The server binds that context to the saved single-use challenge; verify accepts only its exact signed message. API issuer/audience and permissions remain server-owned. Request headers never register an origin. No Renaiss user or SAFE is created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string","maxLength":2048,"format":"uri","description":"Exact registered partner frontend origin (scheme, host and port), without a trailing slash or path.","example":"http://localhost:3100"},"walletAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"scopes":{"type":"array","items":{"type":"string","enum":["gacha:read","redeem:read","redeem:write"]},"minItems":1,"maxItems":3}},"required":["origin","walletAddress","chainId","scopes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"challengeId":{"type":"string","format":"uuid"},"message":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"context":{"type":"object","properties":{"builderAppId":{"type":"string","format":"uuid"},"issuer":{"type":"string","format":"uri"},"audience":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["builderAppId","issuer","audience","scopes"],"description":"Present only for challenges requesting exactly redeem:read and redeem:write. Single redeem scopes and sets including gacha:read keep signed Resources and have no context. SDK validation metadata; do not append it to the message or send it back to verify. Authorization uses the stored challenge, never caller-supplied context."}},"required":["challengeId","message","expiresAt"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder key rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/auth/wallet/verify":{"post":{"tags":["Wallet sessions"],"security":[{"builderAuth":[]}],"summary":"Exchange the exact signed challenge for wallet-session tokens","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"challengeId":{"type":"string","format":"uuid"},"message":{"type":"string","minLength":1,"maxLength":8192},"signature":{"type":"string","maxLength":132}},"required":["challengeId","message","signature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"tokenType":{"type":"string","enum":["Bearer"]},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"refreshExpiresAt":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["tokenType","accessToken","refreshToken","expiresAt","refreshExpiresAt","scopes"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder key rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/auth/wallet/refresh":{"post":{"tags":["Wallet sessions"],"security":[{"builderAuth":[]}],"summary":"Rotate the wallet-session token family","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","minLength":1,"maxLength":128}},"required":["refreshToken"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"tokenType":{"type":"string","enum":["Bearer"]},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"refreshExpiresAt":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["tokenType","accessToken","refreshToken","expiresAt","refreshExpiresAt","scopes"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder key rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/auth/wallet/revoke":{"post":{"tags":["Wallet sessions"],"security":[{"builderAuth":[]}],"summary":"Revoke this wallet-session family","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","minLength":1,"maxLength":128}},"required":["refreshToken"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]}},"required":["revoked"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder key rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/gacha/packs":{"get":{"tags":["Gacha v2"],"summary":"List VRF gacha packs","description":"Returns public VRF gacha pack metadata, including pack and gacha machine video URLs. Use stage to filter by computed public pack stage.","parameters":[{"schema":{"type":"string","enum":["countdown","active","soldout-or-restocking","archived"]},"required":false,"name":"stage","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"cardPacks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"packType":{"type":"string","enum":["limited","perpetual","v3","v3-limited"]},"stage":{"type":"string","enum":["countdown","active","soldout-or-restocking","archived"]},"description":{"type":"string","description":"Pack description as authored: inline-only markdown (**bold**, *italic*, __underline__)"},"priceInUsdt":{"type":"string","pattern":"^[0-9]+$","description":"Pack purchase price in 18-decimal USDT units, serialized as a decimal string."},"expectedValueInUsd":{"type":["string","null"],"pattern":"^[0-9]+$","description":"Stored pack EV metadata in USD cents, serialized as a decimal string; null when unset. For v3 machine display use activeSetExpectedValueInUsd from GET /v2/gacha/packs/{slug}. This field is not recomputed from active or remaining cards."},"featuredCardFmvInUsd":{"type":["string","null"],"pattern":"^[0-9]+$"},"packBannerVideoUrl":{"type":["string","null"]},"gachaMachineVideoUrl":{"type":["string","null"]},"gachaRippingPackAnimationVideoUrl":{"type":["string","null"]},"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"}},"required":["id","slug","name","packType","stage","description","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd","packBannerVideoUrl","gachaMachineVideoUrl","gachaRippingPackAnimationVideoUrl","onChainPackId","vendingMachineAddress"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["cardPacks","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACKS_QUERY_FAILED"],"description":"Possible codes:\n- `CARD_PACKS_QUERY_FAILED`: Failed to query card packs"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/v2/gacha/packs/{slug}/content":{"get":{"tags":["Gacha v2"],"summary":"Preview the VRF pack's eligible card catalog","description":"Preview the cards eligible for this pack, with images, tiers and catalog buyback values. Pagination totals count eligible catalog entries. They do not indicate remaining inventory or guarantee which card a future pull will reveal. Get an actual buyback offer after the pull resolves.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"buybackBaseValueInUsd":{"type":"string","pattern":"^[0-9]+$"},"frontImageUrl":{"type":"string"}},"required":["name","tier","buybackBaseValueInUsd","frontImageUrl"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["cards","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACK_NOT_FOUND"],"description":"Possible codes:\n- `CARD_PACK_NOT_FOUND`: Card pack not found"},"message":{"type":"string"}},"required":["code","message"]}}}},"429":{"description":"Too many requests - upstream rate limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["SUBGRAPH_RATE_LIMITED"],"description":"Possible codes:\n- `SUBGRAPH_RATE_LIMITED`: Subgraph rate limited (429)"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACKS_QUERY_FAILED","FUNCTION_ERROR","INTERNAL_SERVER_ERROR","SUBGRAPH_QUERY_FAILED","SUBGRAPH_REQUEST_FAILED","SUBGRAPH_QUERY_ERROR","SUBGRAPH_INDEXING_ERROR"],"description":"Possible codes:\n- `CARD_PACKS_QUERY_FAILED`: Failed to query card packs\n- `FUNCTION_ERROR`: Function error\n- `INTERNAL_SERVER_ERROR`: An internal server error occurred\n- `SUBGRAPH_QUERY_FAILED`: Failed to query subgraph\n- `SUBGRAPH_REQUEST_FAILED`: Subgraph request failed\n- `SUBGRAPH_QUERY_ERROR`: Subgraph query error\n- `SUBGRAPH_INDEXING_ERROR`: Subgraph indexing error"},"message":{"type":"string"}},"required":["code","message"]}}}},"502":{"description":"Bad gateway - an upstream dependency is unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["SUBGRAPH_NETWORK_ERROR"],"description":"Possible codes:\n- `SUBGRAPH_NETWORK_ERROR`: Subgraph network error"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/v2/gacha/packs/{slug}/pull-history":{"get":{"tags":["Gacha v2"],"summary":"Get VRF gacha pack pull history","description":"Returns cards that have already left this pack, newest first, without repeated pack metadata. Read buybackWindowSeconds from GET /v2/gacha/packs/{slug}. A pull appears here only after its buyback window has closed. The feed therefore runs behind live activity by that window, which is 24 hours on most public packs. The delay is intentional: while the window is open the puller can still sell the card back, so the feed waits until every entry is settled one way or the other. Every entry is on-chain by the time it shows up and can be checked at https://fair.renaiss.xyz/verify-a-rip. No pull time is returned, since any timestamp would describe the reveal rather than the pull. Pagination uses hasMore and covers recent activity. Deep pages may be incomplete, so this feed is not a complete historical export.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":2000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pulls":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"buybackBaseValueInUsd":{"type":"string","pattern":"^[0-9]+$"},"frontImageUrl":{"type":"string","format":"uri"}},"required":["tokenId","name","tier","buybackBaseValueInUsd","frontImageUrl"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["limit","offset","hasMore"]}},"required":["pulls","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Pack not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACK_NOT_FOUND"],"description":"Possible codes:\n- `CARD_PACK_NOT_FOUND`: Card pack not found"},"message":{"type":"string"}},"required":["code","message"]}}}},"429":{"description":"Subgraph rate limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["SUBGRAPH_RATE_LIMITED"],"description":"Possible codes:\n- `SUBGRAPH_RATE_LIMITED`: Subgraph rate limited (429)"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACKS_QUERY_FAILED","FUNCTION_ERROR","INTERNAL_SERVER_ERROR","SUBGRAPH_QUERY_FAILED","SUBGRAPH_REQUEST_FAILED","SUBGRAPH_QUERY_ERROR","SUBGRAPH_INDEXING_ERROR"],"description":"Possible codes:\n- `CARD_PACKS_QUERY_FAILED`: Failed to query card packs\n- `FUNCTION_ERROR`: Function error\n- `INTERNAL_SERVER_ERROR`: An internal server error occurred\n- `SUBGRAPH_QUERY_FAILED`: Failed to query subgraph\n- `SUBGRAPH_REQUEST_FAILED`: Subgraph request failed\n- `SUBGRAPH_QUERY_ERROR`: Subgraph query error\n- `SUBGRAPH_INDEXING_ERROR`: Subgraph indexing error"},"message":{"type":"string"}},"required":["code","message"]}}}},"502":{"description":"Subgraph unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["SUBGRAPH_NETWORK_ERROR"],"description":"Possible codes:\n- `SUBGRAPH_NETWORK_ERROR`: Subgraph network error"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/v2/gacha/packs/{slug}":{"get":{"tags":["Gacha v2"],"summary":"Get VRF gacha pack by slug","description":"Returns public metadata, whole-set rounded tier percentages, storefront catalog value ranges and headline buyback percentage. expectedValueInUsd is stored pack metadata; activeSetExpectedValueInUsd is the whole-set mean used by the renaiss.xyz v3 machine. Neither EV describes remaining undrawn cards. Monetary values are decimal strings: USD uses 2 decimals, USDT uses 18.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"cardPack":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"packType":{"type":"string","enum":["limited","perpetual","v3","v3-limited"]},"stage":{"type":"string","enum":["countdown","active","soldout-or-restocking","archived"]},"description":{"type":"string","description":"Pack description as authored: inline-only markdown (**bold**, *italic*, __underline__)"},"priceInUsdt":{"type":"string","pattern":"^[0-9]+$","description":"Pack purchase price in 18-decimal USDT units, serialized as a decimal string."},"expectedValueInUsd":{"type":["string","null"],"pattern":"^[0-9]+$","description":"Stored pack EV metadata in USD cents, serialized as a decimal string; null when unset. For v3 machine display use activeSetExpectedValueInUsd from GET /v2/gacha/packs/{slug}. This field is not recomputed from active or remaining cards."},"featuredCardFmvInUsd":{"type":["string","null"],"pattern":"^[0-9]+$"},"packBannerVideoUrl":{"type":["string","null"]},"gachaMachineVideoUrl":{"type":["string","null"]},"gachaRippingPackAnimationVideoUrl":{"type":["string","null"]},"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"integer"},"name":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"chance":{"anyOf":[{"type":"number"},{"type":"string","enum":["UNDER-1-PERCENT"]}],"description":"Whole-set tier percentage, rounded to the nearest integer; a positive percentage below 1 is UNDER-1-PERCENT. Rounded tiers need not sum to 100. This is not the probability among remaining undrawn cards."},"priceRangeInUsd":{"type":"object","properties":{"min":{"type":"string","pattern":"^[0-9]+$"},"max":{"type":"string","pattern":"^[0-9]+$"}},"required":["min","max"],"description":"Storefront catalog display range in USD cents, serialized as decimal strings. Min is the configured tier floor; max is the next higher tier's floor, or the public catalog maximum for the highest tier. Not active-set or remaining-card values; not a guaranteed prize range."}},"required":["tier","name","chance","priceRangeInUsd"]}},"activeSetExpectedValueInUsd":{"type":"string","pattern":"^[0-9]+$","description":"Mean base card value across all non-tombstoned slots in the selected active set, including already drawn slots, in USD cents. Uses mandatory formation snapshots, rounded half-up to the nearest cent; 0 for an empty set. This is the EV displayed by the renaiss.xyz v3 machine, before buyback percentage, not the EV of remaining cards or a guaranteed return."},"buybackPercentage":{"type":["number","null"],"description":"Storefront headline instant-buyback percentage, e.g. 85 means 85%. Prefers the selected set's frozen payout percentage; uses the soonest-expiring configured buyback tier only when snapshots cannot supply it. Null when neither exists. Read the buyer's offer for the actual amount and expiry."},"buybackWindowSeconds":{"type":"integer","minimum":0,"description":"Longest buyback window across the pack's tiers. Pulls stay out of /pull-history for this long after they resolve."}},"required":["id","slug","name","packType","stage","description","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd","packBannerVideoUrl","gachaMachineVideoUrl","gachaRippingPackAnimationVideoUrl","onChainPackId","vendingMachineAddress","tiers","activeSetExpectedValueInUsd","buybackPercentage","buybackWindowSeconds"]}},"required":["cardPack"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Pack not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACK_NOT_FOUND"],"description":"Possible codes:\n- `CARD_PACK_NOT_FOUND`: Card pack not found"},"message":{"type":"string"}},"required":["code","message"]}}}},"429":{"description":"Too many requests - upstream rate limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["SUBGRAPH_RATE_LIMITED"],"description":"Possible codes:\n- `SUBGRAPH_RATE_LIMITED`: Subgraph rate limited (429)"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["CARD_PACKS_QUERY_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `CARD_PACKS_QUERY_FAILED`: Failed to query card packs\n- `FUNCTION_ERROR`: Function error"},"message":{"type":"string"}},"required":["code","message"]}}}},"502":{"description":"Bad gateway - an upstream dependency is unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["SUBGRAPH_NETWORK_ERROR"],"description":"Possible codes:\n- `SUBGRAPH_NETWORK_ERROR`: Subgraph network error"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/v2/gacha/pull/prepare":{"post":{"tags":["Gacha v2"],"security":[{"builderAuth":[]}],"summary":"Prepare an EOA purchase and Permit2 typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}],"default":1}},"required":["buyerWalletAddress","packId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"chainId":{"type":"integer","exclusiveMinimum":0},"buyerWalletAddress":{"type":"string"},"pack":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"onChainPackId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"vendingMachineAddress":{"type":"string"}},"required":["id","onChainPackId","priceInUsdt","vendingMachineAddress"]},"permit2TypedData":{"type":"object","properties":{"domain":{"type":"object","properties":{"name":{"type":"string","enum":["Permit2"]},"chainId":{"type":"integer","exclusiveMinimum":0},"verifyingContract":{"type":"string"}},"required":["name","chainId","verifyingContract"]},"types":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"primaryType":{"type":"string","enum":["PermitWitnessTransferFrom"]},"message":{"type":"object","properties":{"permitted":{"type":"object","properties":{"token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["token","amount"]},"spender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"string","pattern":"^\\d+$"},"witness":{"type":"object","properties":{"packId":{"type":"string"},"builder":{"type":"string"},"numOfTokens":{"type":"string","pattern":"^\\d+$"}},"required":["packId","builder","numOfTokens"]}},"required":["permitted","spender","nonce","deadline","witness"]}},"required":["domain","types","primaryType","message"]},"unsignedPullPayload":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"builderCode":{"type":"string"},"numOfTokens":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}]},"amountPerToken":{"type":"string","pattern":"^\\d+$"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"integer","exclusiveMinimum":0}},"required":["packId","builderCode","numOfTokens","amountPerToken","nonce","deadline"]}},"required":["chainId","buyerWalletAddress","pack","permit2TypedData","unsignedPullPayload"]},{"type":"object","properties":{"accountType":{"type":"string","enum":["EOA"]},"approval":{"type":"object","properties":{"token":{"type":"string"},"spender":{"type":"string"},"requiredAmount":{"type":"string"}},"required":["token","spender","requiredAmount"]}},"required":["accountType","approval"]}]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}]}}}},"401":{"description":"Invalid builder credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"403":{"description":"Wallet authorization rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Conflicting request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder API key rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["API_AUTH_RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/gacha/pull/stream":{"post":{"tags":["Gacha v2"],"security":[{"builderAuth":[]}],"summary":"Submit a signed EOA pull and stream through card resolution","description":"Requires a builder key AND a valid Permit2 wallet action signature over the full pull payload. No wallet session is required. Emits pull_started, payment_queued, payment_submitting, payment_confirmed, then draws_resolved with all purchased cards. Only draws_resolved means success; pull_failed ends an unsuccessful stream. See GachaV2PullStreamEvent for payload schemas. Every result belongs to the builder identified by your API key and the requested buyer wallet. Save permitFundTxHash from payment_confirmed; use draw-status/history to recover after disconnect or timeout. Do not automatically retry an uncertain submission or sign a fresh nonce before reconciling the original purchase.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"numOfTokens":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}]},"amountPerToken":{"type":"string","pattern":"^\\d+$"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"integer","exclusiveMinimum":0},"buyerWalletAddress":{"type":"string"},"permitSignature":{"type":"string"}},"required":["packId","numOfTokens","amountPerToken","nonce","deadline","buyerWalletAddress","permitSignature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Five named SSE stages through draws_resolved, or terminal pull_failed. Keep-alive comments are not application events. No happy-path status polling is required.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}]}}}},"401":{"description":"Invalid builder credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"403":{"description":"Wallet authorization rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Conflicting request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder API key rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["API_AUTH_RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/gacha/draw-status":{"get":{"tags":["Gacha v2"],"security":[{"builderAuth":[]}],"summary":"Get this builder's EOA pull status by confirmed funding transaction","description":"Requires only the builder API key. The requested EOA and funding transaction must belong to the verified builder code; another builder's transaction returns 404. Omit wallet-session bearer tokens.","parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerWalletAddress","in":"query"},{"schema":{"type":"string"},"required":true,"name":"permitFundTxHash","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"permitFundTxHash":{"type":"string"},"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"packName":{"type":"string"},"status":{"type":"string","enum":["PENDING_RESOLUTION","RESOLVED"]},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"pulledAt":{"type":["string","null"],"format":"date-time"},"draws":{"type":"array","items":{"type":"object","properties":{"settlementId":{"type":"string"},"tokenId":{"type":"string"},"releaseTxHash":{"type":["string","null"]},"buybackTxHash":{"type":["string","null"]}},"required":["settlementId","tokenId","releaseTxHash","buybackTxHash"]}}},"required":["permitFundTxHash","buyerWalletAddress","packId","packName","status","numOfTokens","pulledAt","draws"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}]}}}},"401":{"description":"Invalid builder credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"403":{"description":"Wallet authorization rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Conflicting request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder API key rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["API_AUTH_RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/gacha/pull-history":{"get":{"tags":["Gacha v2"],"security":[{"builderAuth":[]}],"summary":"List this builder's resolved EOA pulls, grouped by funding transaction","description":"Requires only the builder API key. Filters by the requested EOA and the builder code from that key before pagination. No records from another builder are returned. Omit wallet-session bearer tokens.","parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerWalletAddress","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pulls":{"type":"array","items":{"type":"object","properties":{"permitFundTxHash":{"type":"string"},"buyerWalletAddress":{"type":"string"},"packId":{"type":"string","format":"uuid"},"packName":{"type":"string"},"status":{"type":"string","enum":["PENDING_RESOLUTION","RESOLVED"]},"numOfTokens":{"type":"integer","exclusiveMinimum":0},"pulledAt":{"type":["string","null"],"format":"date-time"},"draws":{"type":"array","items":{"type":"object","properties":{"settlementId":{"type":"string"},"tokenId":{"type":"string"},"releaseTxHash":{"type":["string","null"]},"buybackTxHash":{"type":["string","null"]}},"required":["settlementId","tokenId","releaseTxHash","buybackTxHash"]}}},"required":["permitFundTxHash","buyerWalletAddress","packId","packName","status","numOfTokens","pulledAt","draws"]}},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["pulls","limit","offset","hasMore"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}]}}}},"401":{"description":"Invalid builder credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"403":{"description":"Wallet authorization rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Conflicting request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder API key rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["API_AUTH_RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/gacha/buyback/offers":{"get":{"tags":["Gacha v2"],"security":[{"builderAuth":[]}],"summary":"List eligible buybacks from this builder's EOA draws","description":"Requires only the builder API key. Returns eligible draws for the requested EOA attributed to the builder code from that key. Omit wallet-session bearer tokens. Accepting a buyback still requires the EOA action signature.","parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerWalletAddress","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"cardPackId":{"type":"string"},"settlementId":{"type":"string"},"tokenId":{"type":"string"},"amountInUsdt":{"type":"string"},"expiresAt":{"type":"string"},"vendingMachineAddress":{"type":"string"}},"required":["cardPackId","settlementId","tokenId","amountInUsdt","expiresAt","vendingMachineAddress"]}}},"required":["offers"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}]}}}},"401":{"description":"Invalid builder credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"403":{"description":"Wallet authorization rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Conflicting request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder API key rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["API_AUTH_RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/gacha/buyback":{"post":{"tags":["Gacha v2"],"security":[{"builderAuth":[]}],"summary":"Settle this builder's EOA draws using a direct EOA signature","description":"Requires a builder key AND a wallet signature over BuybackUserAuthorization. A wallet session cannot replace the signature.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"cardPackId":{"type":"string","format":"uuid"},"buybackAuth":{"type":"object","properties":{"buybackIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10},"token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["buybackIds","token","amount"]},"userSignature":{"type":"string"}},"required":["buyerWalletAddress","cardPackId","buybackAuth","userSignature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string"},"totalAmountInUsdt":{"type":"string","pattern":"^[0-9]+$"},"itemCount":{"type":"integer","minimum":1}},"required":["txHash","totalAmountInUsdt","itemCount"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}]}}}},"401":{"description":"Invalid builder credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"403":{"description":"Wallet authorization rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Conflicting request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Builder API key rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["API_AUTH_RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/asks/prepare":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Prepare a direct EOA listing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"walletAddress":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":31536000},"totalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"sellerReceivesInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["tokenId","walletAddress"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["ask"]},"tokenId":{"type":"string","pattern":"^\\d+$"},"sellerWalletAddress":{"type":"string"},"quote":{"type":"object","properties":{"sellerReceivesInUsdt":{"type":"string","pattern":"^\\d+$"},"platformFeeInUsdt":{"type":"string","pattern":"^\\d+$"},"totalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["sellerReceivesInUsdt","platformFeeInUsdt","totalPriceInUsdt","expiresAt"]},"typedData":{"type":"object","properties":{"domain":{"type":"object","additionalProperties":{}},"types":{"type":"object","additionalProperties":{}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]},"payload":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"askData":{"type":"object","properties":{"salt":{"type":"string"},"deadline":{"type":"string","pattern":"^\\d+$"},"usdcAmount":{"type":"string","pattern":"^\\d+$"},"owner":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["salt","deadline","usdcAmount","owner","tokenId"]}},"required":["collectibleId","askData"]}},"required":["operation","tokenId","sellerWalletAddress","quote","typedData","payload"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/bids/prepare":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Prepare a direct EOA bid","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"walletAddress":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":31536000},"amountInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["tokenId","walletAddress","amountInUsdt"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["bid","buy"]},"tokenId":{"type":"string","pattern":"^\\d+$"},"buyerWalletAddress":{"type":"string"},"quote":{"type":"object","properties":{"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["amountInUsdt","expiresAt"]},"typedData":{"type":"object","properties":{"domain":{"type":"object","additionalProperties":{}},"types":{"type":"object","additionalProperties":{}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]},"payload":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"bidData":{"type":"object","properties":{"bidder":{"type":"string"},"feeBps":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"string","pattern":"^\\d+$"}},"required":["bidder","feeBps","tokenId","amount","nonce","deadline"]}},"required":["collectibleId","bidData"]}},"required":["operation","tokenId","buyerWalletAddress","quote","typedData","payload"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/buy/prepare":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Prepare an EOA purchase at the displayed ask price","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"walletAddress":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":31536000},"expectedTotalPriceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["tokenId","walletAddress","expectedTotalPriceInUsdt"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["bid","buy"]},"tokenId":{"type":"string","pattern":"^\\d+$"},"buyerWalletAddress":{"type":"string"},"quote":{"type":"object","properties":{"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["amountInUsdt","expiresAt"]},"typedData":{"type":"object","properties":{"domain":{"type":"object","additionalProperties":{}},"types":{"type":"object","additionalProperties":{}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]},"payload":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"bidData":{"type":"object","properties":{"bidder":{"type":"string"},"feeBps":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"string","pattern":"^\\d+$"}},"required":["bidder","feeBps","tokenId","amount","nonce","deadline"]}},"required":["collectibleId","bidData"]}},"required":["operation","tokenId","buyerWalletAddress","quote","typedData","payload"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/sell/prepare":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Prepare an EOA acceptance of a bid","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"walletAddress":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":31536000},"bidOrderId":{"type":"string","format":"uuid"}},"required":["tokenId","walletAddress","bidOrderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["sell"]},"tokenId":{"type":"string","pattern":"^\\d+$"},"sellerWalletAddress":{"type":"string"},"quote":{"type":"object","properties":{"sellerReceivesInUsdt":{"type":"string","pattern":"^\\d+$"},"platformFeeInUsdt":{"type":"string","pattern":"^\\d+$"},"totalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"bidOrderId":{"type":"string","format":"uuid"},"bidderWalletAddress":{"type":"string"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["sellerReceivesInUsdt","platformFeeInUsdt","totalPriceInUsdt","expiresAt","bidOrderId","bidderWalletAddress","amountInUsdt"]},"typedData":{"type":"object","properties":{"domain":{"type":"object","additionalProperties":{}},"types":{"type":"object","additionalProperties":{}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]},"payload":{"type":"object","properties":{"bidOrderId":{"type":"string","format":"uuid"},"collectibleId":{"type":"string","format":"uuid"},"askData":{"type":"object","properties":{"salt":{"type":"string"},"deadline":{"type":"string","pattern":"^\\d+$"},"usdcAmount":{"type":"string","pattern":"^\\d+$"},"owner":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["salt","deadline","usdcAmount","owner","tokenId"]}},"required":["bidOrderId","collectibleId","askData"]}},"required":["operation","tokenId","sellerWalletAddress","quote","typedData","payload"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/asks":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Submit an EOA-signed listing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"askData":{"type":"object","properties":{"salt":{"type":"string"},"deadline":{"type":"string","pattern":"^\\d+$"},"usdcAmount":{"type":"string","pattern":"^\\d+$"},"owner":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["salt","deadline","usdcAmount","owner","tokenId"]},"askSignature":{"type":"string"}},"required":["collectibleId","askData","askSignature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["ask","bid","buy","sell"]},"orderId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","EXECUTED"]},"executed":{"type":"boolean"},"executionTxHash":{"type":"string"},"matchedOrderId":{"type":"string"}},"required":["operation","orderId","status","executed"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/bids":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Submit an EOA-signed bid","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"bidData":{"type":"object","properties":{"bidder":{"type":"string"},"feeBps":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"string","pattern":"^\\d+$"}},"required":["bidder","feeBps","tokenId","amount","nonce","deadline"]},"bidSignature":{"type":"string"}},"required":["collectibleId","bidData","bidSignature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["ask","bid","buy","sell"]},"orderId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","EXECUTED"]},"executed":{"type":"boolean"},"executionTxHash":{"type":"string"},"matchedOrderId":{"type":"string"}},"required":["operation","orderId","status","executed"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/buy":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Submit an EOA-signed purchase","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"bidData":{"type":"object","properties":{"bidder":{"type":"string"},"feeBps":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"},"nonce":{"type":"string","pattern":"^\\d+$"},"deadline":{"type":"string","pattern":"^\\d+$"}},"required":["bidder","feeBps","tokenId","amount","nonce","deadline"]},"bidSignature":{"type":"string"}},"required":["collectibleId","bidData","bidSignature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["ask","bid","buy","sell"]},"orderId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","EXECUTED"]},"executed":{"type":"boolean"},"executionTxHash":{"type":"string"},"matchedOrderId":{"type":"string"}},"required":["operation","orderId","status","executed"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/sell":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Submit an EOA-signed bid acceptance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectibleId":{"type":"string","format":"uuid"},"askData":{"type":"object","properties":{"salt":{"type":"string"},"deadline":{"type":"string","pattern":"^\\d+$"},"usdcAmount":{"type":"string","pattern":"^\\d+$"},"owner":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["salt","deadline","usdcAmount","owner","tokenId"]},"askSignature":{"type":"string"},"bidOrderId":{"type":"string","format":"uuid"}},"required":["collectibleId","askData","askSignature","bidOrderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["ask","bid","buy","sell"]},"orderId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","EXECUTED"]},"executed":{"type":"boolean"},"executionTxHash":{"type":"string"},"matchedOrderId":{"type":"string"}},"required":["operation","orderId","status","executed"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/orders/cancel/prepare":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Prepare a signature to remove one exact EOA order from the off-chain book","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"walletAddress":{"type":"string"}},"required":["orderId","walletAddress"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"walletAddress":{"type":"string"},"deadline":{"type":"string","pattern":"^\\d+$"}},"required":["orderId","walletAddress","deadline"]},"typedData":{"type":"object","properties":{"domain":{"type":"object","additionalProperties":{}},"types":{"type":"object","additionalProperties":{}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]}},"required":["payload","typedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/orders/cancel":{"post":{"tags":["Marketplace"],"security":[{"builderAuth":[]}],"summary":"Remove one EOA order using its owner's signed authorization","description":"Off-chain cancellation only. It does not invalidate the underlying on-chain ask or Permit2 signature. The signature binds the exact order, builder, chain and five-minute deadline.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"walletAddress":{"type":"string"},"deadline":{"type":"string","pattern":"^\\d+$"},"signature":{"type":"string"}},"required":["orderId","walletAddress","deadline","signature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CANCELLED"]}},"required":["orderId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace":{"get":{"tags":["Marketplace"],"summary":"Browse the public marketplace","description":"Public catalog with storefront filters and display images. Prices are integer strings: USDT uses 18 decimals; USD uses cents. No credentials accepted.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["POKEMON","ONE_PIECE"]},"required":false,"name":"categoryFilter","in":"query"},{"schema":{"type":"string"},"required":false,"name":"characterFilter","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","enum":["Chinese"],"description":"this exists here and not in enum definition because it's not actually stored in db"},{"type":"string","enum":["English","Japanese","Traditional Chinese","Simplified Chinese","Korean","Indonesian","Portuguese","Italian","German","Polish","French","Spanish"]}]},"required":false,"name":"languageFilter","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","enum":["PSA","BGS","CGC","SGC"]}]},"required":false,"name":"gradingCompanyFilter","in":"query"},{"schema":{"type":"string"},"required":false,"name":"gradeFilter","in":"query"},{"schema":{"type":"string"},"required":false,"name":"yearRange","in":"query"},{"schema":{"type":"string"},"required":false,"name":"priceRangeFilter","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"listedOnly","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["listDate","mintDate","name","year","priceRange","askPriceInUSDT","fmvPriceInUsd"],"default":"listDate"},"required":false,"name":"sortBy","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","description":"Decimal token ID, serialized losslessly","pattern":"^\\d+$"},"name":{"type":"string"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"askPriceInUSDT":{"type":"string","description":"18-decimal USDT base units, or NO-ASK-PRICE"},"fmvPriceInUSD":{"type":"string","description":"USD cents, or NO-FMV-PRICE"},"fmvUpdatedAt":{"type":["string","null"]},"frontImageUrl":{"type":"string","format":"uri"}},"required":["tokenId","name","ownerAddress","askPriceInUSDT","fmvPriceInUSD","frontImageUrl"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["collection","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/cards/{tokenId}":{"get":{"tags":["Marketplace"],"summary":"Get public card details and price history","description":"Only visible cards are returned. Excludes inventory awaiting release, private reservations and buyback authorizations. No credentials accepted.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"tokenId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"collectible":{"type":"object","properties":{"tokenId":{"type":"string","description":"Decimal token ID, serialized losslessly","pattern":"^\\d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"pokemonName":{"type":"string"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"askPriceInUSDT":{"type":"string","description":"18-decimal USDT base units, or NO-ASK-PRICE"},"askExpiresAt":{"type":"string"},"fmvPriceInUSD":{"type":"string","description":"USD cents, or NO-FMV-PRICE"},"fmvUpdatedAt":{"type":["string","null"]},"frontImageUrl":{"type":"string","format":"uri"},"attributes":{"type":"array","items":{"type":"object","properties":{"trait":{"type":"string"},"value":{"type":"string"}},"required":["trait","value"]}},"gradingCompany":{"type":"string"},"grade":{"type":"string"},"year":{"type":"integer","exclusiveMinimum":0},"owner":{"type":["object","null"],"properties":{"username":{"type":"string"},"image":{"type":"string","format":"uri"}},"required":["username"]},"custodyProvider":{"type":"object","properties":{"businessName":{"type":"string"},"countryCode":{"type":"string"}},"required":["businessName","countryCode"]},"backImageUrl":{"type":"string","format":"uri"},"frontWithoutStandImageUrl":{"type":"string","format":"uri"}},"required":["tokenId","name","setName","cardNumber","pokemonName","ownerAddress","askPriceInUSDT","fmvPriceInUSD","frontImageUrl","attributes","gradingCompany","grade","year","owner"]},"pricing":{"type":"object","properties":{"top_offer":{"type":["object","null"],"properties":{"value":{"type":"string"},"token":{"anyOf":[{"type":"string","enum":["USDT"]},{"type":"string","enum":["USD"]}]}},"required":["value","token"]},"last_sale":{"type":["object","null"],"properties":{"value":{"type":"string"},"token":{"anyOf":[{"type":"string","enum":["USDT"]},{"type":"string","enum":["USD"]}]}},"required":["value","token"]},"price_history":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"amount":{"type":"object","properties":{"value":{"type":"string"},"token":{"anyOf":[{"type":"string","enum":["USDT"]},{"type":"string","enum":["USD"]}]}},"required":["value","token"]}},"required":["timestamp","amount"]}}},"required":["top_offer","last_sale","price_history"]}},"required":["collectible","pricing"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/marketplace/cards/{tokenId}/orders":{"get":{"tags":["Marketplace"],"summary":"Get the active ask and funded bids for a visible card","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"tokenId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"activeAsk":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"ownerAddress":{"type":"string"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","ownerAddress","amountInUsdt","expiresAt"]},"activeBids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ownerAddress":{"type":"string"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","ownerAddress","amountInUsdt","expiresAt","createdAt"]}}},"required":["tokenId","activeAsk","activeBids"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/cards":{"get":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"List this EOA's eligible redemption cards","parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"required":false,"name":"countryCode","in":"query"},{"schema":{"type":"string","enum":["createdAt","fmv"],"default":"fmv"},"required":false,"name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d{1,78}$"},"name":{"type":"string"},"frontImageUrl":{"type":"string","format":"uri"},"fmvPriceInUsd":{"type":["string","null"],"pattern":"^\\d{1,78}$"},"fmvUpdatedAt":{"type":["string","null"],"format":"date-time"},"ownerAcquiredAt":{"type":["string","null"],"format":"date-time"},"regionCountryCode":{"type":"string"},"vaultDisplayName":{"type":"string"}},"required":["tokenId","name","frontImageUrl","fmvPriceInUsd","fmvUpdatedAt","ownerAcquiredAt","regionCountryCode","vaultDisplayName"]}},"total":{"type":"integer"},"page":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["cards","total","page","hasMore"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/regions":{"get":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Count this EOA's redeemable cards by region","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["counts"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/address/validate":{"post":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Validate a shipping address","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"addressLine1":{"type":"string","minLength":1,"maxLength":35},"addressLine2":{"type":"string","maxLength":35},"city":{"type":"string","minLength":1,"maxLength":200},"state":{"type":"string","maxLength":200},"postalCode":{"type":"string","minLength":1,"maxLength":20}},"required":["countryCode","addressLine1","city","postalCode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"detail":{"type":"string"}},"required":["status","detail"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/quotes":{"post":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Quote shipping for the authenticated EOA's exact cart","description":"Server-calculated rates expire after ten minutes. Duties and taxes are payable on delivery and excluded from the checkout total.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenIds":{"type":"array","items":{"type":"string","pattern":"^\\d{1,78}$"},"minItems":1,"maxItems":50},"address":{"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"addressLine1":{"type":"string","minLength":1,"maxLength":35},"addressLine2":{"type":"string","maxLength":35},"city":{"type":"string","minLength":1,"maxLength":200},"state":{"type":"string","maxLength":200},"postalCode":{"type":"string","minLength":1,"maxLength":20}},"required":["countryCode","addressLine1","city","postalCode"],"additionalProperties":false}},"required":["tokenIds","address"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"handlingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"couriers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"logoUrl":{"type":["string","null"]},"estimatedDays":{"type":"string"},"shippingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"insuranceFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"dutyAndTaxesInUsd":{"type":"string","pattern":"^\\d{1,78}$"}},"required":["id","name","logoUrl","estimatedDays","shippingFeeInUsd","insuranceFeeInUsd","dutyAndTaxesInUsd"]}}},"required":["quoteId","expiresAt","handlingFeeInUsd","couriers"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/checkout/prepare":{"post":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Prepare an EOA Permit2 redemption from a saved quote","description":"Binds the exact card set, recipient, destination, courier, price and builder on the server. The user signs one Permit2 witness authorization. Never accept fee amounts from the client.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","format":"uuid"},"courierId":{"type":"string"},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":22},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","maxLength":50,"format":"email"},"taxId":{"type":"string","maxLength":100},"chineseName":{"type":"string","maxLength":100}},"required":["name","phone","email"],"additionalProperties":false},"insurance":{"type":"boolean"}},"required":["quoteId","courierId","recipient","insurance"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"preparationId":{"type":"string","format":"uuid"},"requestId":{"type":"string"},"walletAddress":{"type":"string"},"tokenIds":{"type":"array","items":{"type":"string","pattern":"^\\d{1,78}$"},"minItems":1,"maxItems":50},"expiresAt":{"type":"string","format":"date-time"},"address":{"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"addressLine1":{"type":"string","minLength":1,"maxLength":35},"addressLine2":{"type":"string","maxLength":35},"city":{"type":"string","minLength":1,"maxLength":200},"state":{"type":"string","maxLength":200},"postalCode":{"type":"string","minLength":1,"maxLength":20}},"required":["countryCode","addressLine1","city","postalCode"],"additionalProperties":false},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":22},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","maxLength":50,"format":"email"},"taxId":{"type":"string","maxLength":100},"chineseName":{"type":"string","maxLength":100}},"required":["name","phone","email"],"additionalProperties":false},"courierName":{"type":"string"},"fees":{"type":"object","properties":{"handlingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"shippingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"insuranceFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"dutyAndTaxesInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"totalFeeInUsdt":{"type":"string","pattern":"^\\d{1,78}$"}},"required":["handlingFeeInUsd","shippingFeeInUsd","insuranceFeeInUsd","dutyAndTaxesInUsd","totalFeeInUsdt"]},"redemptionTypedData":{"type":"object","properties":{"domain":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"chainId":{"type":"integer"},"verifyingContract":{"type":"string"}},"required":["name","chainId","verifyingContract"]},"types":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]},"permitTypedData":{"type":"object","properties":{"domain":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"chainId":{"type":"integer"},"verifyingContract":{"type":"string"}},"required":["name","chainId","verifyingContract"]},"types":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{}}},"required":["domain","types","primaryType","message"]}},"required":["preparationId","requestId","walletAddress","tokenIds","expiresAt","address","recipient","courierName","fees","redemptionTypedData","permitTypedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/checkout":{"post":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Submit a prepared EOA redemption once","description":"Never automatically retry a payment. A repeated preparation ID returns its recorded state; use checkout status and order reads to reconcile interruptions. This starts redemption but does not create or dispatch a shipment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preparationId":{"type":"string","format":"uuid"},"signature":{"type":"string","pattern":"^0x(?:[a-fA-F0-9]{128}|[a-fA-F0-9]{130})$"}},"required":["preparationId","signature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["prepared","submitting","succeeded","failed"]},"transactionHash":{"type":"string"}},"required":["requestId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/checkout/{preparationId}":{"get":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Reconcile a submitted redemption preparation","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"preparationId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["prepared","submitting","succeeded","failed"]},"transactionHash":{"type":"string"}},"required":["requestId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/orders":{"get":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"List this builder and EOA's redemption orders","description":"Scope is applied before pagination. Newly submitted orders may not appear until indexed; continue using checkout status during that interval.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":20,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string"},"trackingNumber":{"type":["string","null"]},"shipmentStatus":{"type":["string","null"]},"shipmentProvider":{"type":"string","enum":["easyship","manual","cc"]},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d{1,78}$"},"name":{"type":"string"},"frontImageUrl":{"type":"string","format":"uri"},"fmvPriceInUsd":{"type":["string","null"],"pattern":"^\\d{1,78}$"}},"required":["tokenId","name","frontImageUrl","fmvPriceInUsd"]}}},"required":["requestId","status","trackingNumber","shipmentStatus","shipmentProvider","cards"]}},"hasMore":{"type":"boolean"}},"required":["orders","hasMore"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/orders/{requestId}":{"get":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Read owner-only redemption and shipping details","parameters":[{"schema":{"type":"string","pattern":"^0x[\\da-fA-F]{64}$"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string"},"tokenStatuses":{"type":"object","additionalProperties":{"type":"string"}},"address":{"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"addressLine1":{"type":"string","minLength":1,"maxLength":35},"addressLine2":{"type":"string","maxLength":35},"city":{"type":"string","minLength":1,"maxLength":200},"state":{"type":"string","maxLength":200},"postalCode":{"type":"string","minLength":1,"maxLength":20}},"required":["countryCode","addressLine1","city","postalCode"],"additionalProperties":false},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":22},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","maxLength":50,"format":"email"},"chineseName":{"type":"string","maxLength":100}},"required":["name","phone","email"],"additionalProperties":false},"courierName":{"type":"string"},"estimatedDeliveryDaysMin":{"type":["number","null"]},"estimatedDeliveryDaysMax":{"type":["number","null"]},"fees":{"type":"object","properties":{"handlingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"shippingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"insuranceFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"dutyAndTaxesInUsd":{"type":"string","pattern":"^\\d{1,78}$"}},"required":["handlingFeeInUsd","shippingFeeInUsd","insuranceFeeInUsd","dutyAndTaxesInUsd"]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"shipmentStatus":{"type":["string","null"]},"shipmentProvider":{"type":"string","enum":["easyship","manual","cc"]},"trackingLastSyncedAt":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d{1,78}$"},"name":{"type":"string"},"frontImageUrl":{"type":"string","format":"uri"},"fmvPriceInUsd":{"type":["string","null"],"pattern":"^\\d{1,78}$"},"fmvUpdatedAt":{"type":["string","null"],"format":"date-time"},"regionCountryCode":{"type":"string"},"vaultDisplayName":{"type":"string"}},"required":["tokenId","name","frontImageUrl","fmvPriceInUsd","fmvUpdatedAt","regionCountryCode","vaultDisplayName"]}}},"required":["requestId","status","tokenStatuses","address","recipient","courierName","estimatedDeliveryDaysMin","estimatedDeliveryDaysMax","fees","trackingNumber","trackingUrl","shipmentStatus","shipmentProvider","trackingLastSyncedAt","createdAt","updatedAt","cards"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}},"/v2/redeem/orders/{requestId}/tracking":{"post":{"tags":["Redemption"],"security":[{"builderAuth":[],"walletSession":[]}],"summary":"Refresh tracking for an authorized redemption order","parameters":[{"schema":{"type":"string","pattern":"^0x[\\da-fA-F]{64}$"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string"},"tokenStatuses":{"type":"object","additionalProperties":{"type":"string"}},"address":{"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"addressLine1":{"type":"string","minLength":1,"maxLength":35},"addressLine2":{"type":"string","maxLength":35},"city":{"type":"string","minLength":1,"maxLength":200},"state":{"type":"string","maxLength":200},"postalCode":{"type":"string","minLength":1,"maxLength":20}},"required":["countryCode","addressLine1","city","postalCode"],"additionalProperties":false},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":22},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","maxLength":50,"format":"email"},"chineseName":{"type":"string","maxLength":100}},"required":["name","phone","email"],"additionalProperties":false},"courierName":{"type":"string"},"estimatedDeliveryDaysMin":{"type":["number","null"]},"estimatedDeliveryDaysMax":{"type":["number","null"]},"fees":{"type":"object","properties":{"handlingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"shippingFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"insuranceFeeInUsd":{"type":"string","pattern":"^\\d{1,78}$"},"dutyAndTaxesInUsd":{"type":"string","pattern":"^\\d{1,78}$"}},"required":["handlingFeeInUsd","shippingFeeInUsd","insuranceFeeInUsd","dutyAndTaxesInUsd"]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"shipmentStatus":{"type":["string","null"]},"shipmentProvider":{"type":"string","enum":["easyship","manual","cc"]},"trackingLastSyncedAt":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d{1,78}$"},"name":{"type":"string"},"frontImageUrl":{"type":"string","format":"uri"},"fmvPriceInUsd":{"type":["string","null"],"pattern":"^\\d{1,78}$"},"fmvUpdatedAt":{"type":["string","null"],"format":"date-time"},"regionCountryCode":{"type":"string"},"vaultDisplayName":{"type":"string"}},"required":["tokenId","name","frontImageUrl","fmvPriceInUsd","fmvUpdatedAt","regionCountryCode","vaultDisplayName"]}}},"required":["requestId","status","tokenStatuses","address","recipient","courierName","estimatedDeliveryDaysMin","estimatedDeliveryDaysMax","fees","trackingNumber","trackingUrl","shipmentStatus","shipmentProvider","trackingLastSyncedAt","createdAt","updatedAt","cards"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}}}}}},"webhooks":{},"tags":[{"name":"Gacha v2","description":"Direct-EOA pack browsing, purchases, card reveals, purchase history and buybacks. Start here; wallet-session setup is not required."},{"name":"Marketplace","description":"Public card browsing and direct-EOA asks, bids, purchases and cancellations. Trading requires builder authorization and wallet action signatures."},{"name":"Redemption","description":"Shipping eligibility, quotes, redemption preparation, submission and tracking. Requires both builder authorization and a matching wallet session."},{"name":"Wallet sessions","description":"Verify a wallet for private shipping access. Register exact partner frontend origins with Renaiss before use. Gacha and marketplace do not require this sign-in."}],"x-wallet-session-issuer":"https://dev-api.renaiss.xyz/v2/auth/wallet"}