{"openapi":"3.1.1","info":{"version":"1.0.0","title":"Renaiss API (v2)","description":"EOA-only builder gacha and marketplace evaluation API. Gacha purchases require pilot enablement. No Renaiss SAFE or social onboarding."},"servers":[{"url":"/","description":"API root"}],"components":{"securitySchemes":{"walletSession":{"type":"http","scheme":"bearer","description":"Builder-bound EOA wallet session with redeem:read/redeem:write scope"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Better Auth session token","description":"Paste the Better Auth session token without the `Bearer ` prefix. Used to create API keys."},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Paste the API key returned by POST /api/auth/api-key/create."},"oauthAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"OAuth 2.1 access token","description":"Access token from \"Sign in with Renaiss\" (the /oauth2/token exchange), pasted without the `Bearer ` prefix. Authorizes a partner to act for the user who consented, and only within the scopes on the token."},"builderAuth":{"type":"apiKey","in":"header","name":"x-builder-api-key","description":"Approved builder/app Better Auth API key. On gacha v3 and wallet setup it authorizes the call on its own, with the wallet address named in the request. Marketplace writes still require it alongside x-api-key."}},"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","minimum":0,"exclusiveMinimum":true},"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","minimum":0,"exclusiveMinimum":true},"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","minimum":0,"exclusiveMinimum":true},"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","minimum":0,"exclusiveMinimum":true},"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","minimum":0,"exclusiveMinimum":true},"message":{"type":"string"},"permitFundTxHash":{"type":"string"},"packName":{"type":"string"},"status":{"type":"string","enum":["RESOLVED"]},"pulledAt":{"type":"string","nullable":true,"format":"date-time"},"draws":{"type":"array","items":{"type":"object","properties":{"settlementId":{"type":"string"},"tokenId":{"type":"string"},"releaseTxHash":{"type":"string","nullable":true},"buybackTxHash":{"type":"string","nullable":true},"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","nullable":true}},"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","minimum":0,"exclusiveMinimum":true},"message":{"type":"string"},"code":{"type":"string"},"error":{"type":"string"},"permitFundTxHash":{"type":"string","nullable":true},"fundingConfirmed":{"type":"boolean"}},"required":["buyerWalletAddress","packId","nonce","numOfTokens","message","code","error","permitFundTxHash","fundingConfirmed"]}},"required":["event","data"]}]}},"parameters":{}},"paths":{"/v2/auth/wallet/nonce":{"post":{"tags":["EOA wallet sessions"],"security":[{"builderAuth":[]}],"summary":"Create an EOA sign-in challenge for this builder","description":"Call through the builder backend. Select an exact origin from this builder's server registration; it supplies the SIWE scheme, domain and URI. 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","minimum":0,"exclusiveMinimum":true},"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"}},"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":["EOA 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":["EOA 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":["EOA 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","nullable":true,"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":"^d+$","description":"Pack purchase price in 18-decimal USDT units, serialized as a decimal string."},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$","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","nullable":true,"pattern":"^d+$"},"packBannerVideoUrl":{"type":"string","nullable":true},"gachaMachineVideoUrl":{"type":"string","nullable":true},"gachaRippingPackAnimationVideoUrl":{"type":"string","nullable":true},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v2/gacha/packs/{slug}/content":{"get":{"tags":["Gacha v2"],"summary":"Preview the VRF pack's eligible card catalog","description":"Uses the same eligible-catalog reader as renaiss.xyz. Cards and values are catalog previews, not the active set or its remaining inventory. Pagination totals count catalog entries, not undrawn cards. No collectible/token IDs, set membership, slot status, frozen values, selection order or internal tier targets are returned.","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","nullable":true,"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":"^d+$"},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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 duplicated pack metadata. Read the pack-wide buyback window 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 is hasMore-only and best-effort past the first few hundred entries: the feed merges two capped subgraph streams, so a deep page may come back short with hasMore false while older history still exists.","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","nullable":true,"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":"^d+$"},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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":"^d+$","description":"Pack purchase price in 18-decimal USDT units, serialized as a decimal string."},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$","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","nullable":true,"pattern":"^d+$"},"packBannerVideoUrl":{"type":"string","nullable":true},"gachaMachineVideoUrl":{"type":"string","nullable":true},"gachaRippingPackAnimationVideoUrl":{"type":"string","nullable":true},"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":"^d+$"},"max":{"type":"string","pattern":"^d+$"}},"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":"^d+$","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","nullable":true,"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"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","minimum":0,"exclusiveMinimum":true},"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","minimum":0,"exclusiveMinimum":true},"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","minimum":0,"exclusiveMinimum":true}},"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":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"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. Builder attribution comes from the credential and is checked again before revealing cards. Save permitFundTxHash from payment_confirmed; use draw-status/history to recover after disconnect or timeout. This endpoint has no durable HTTP idempotency key: do not automatically retry an uncertain submission or sign a fresh nonce to retry it.","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","minimum":0,"exclusiveMinimum":true},"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":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"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","minimum":0,"exclusiveMinimum":true},"pulledAt":{"type":"string","nullable":true,"format":"date-time"},"draws":{"type":"array","items":{"type":"object","properties":{"settlementId":{"type":"string"},"tokenId":{"type":"string"},"releaseTxHash":{"type":"string","nullable":true},"buybackTxHash":{"type":"string","nullable":true}},"required":["settlementId","tokenId","releaseTxHash","buybackTxHash"]}}},"required":["permitFundTxHash","buyerWalletAddress","packId","packName","status","numOfTokens","pulledAt","draws"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"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","nullable":true,"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","minimum":0,"exclusiveMinimum":true},"pulledAt":{"type":"string","nullable":true,"format":"date-time"},"draws":{"type":"array","items":{"type":"object","properties":{"settlementId":{"type":"string"},"tokenId":{"type":"string"},"releaseTxHash":{"type":"string","nullable":true},"buybackTxHash":{"type":"string","nullable":true}},"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":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"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","nullable":true,"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":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"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":"^d+$"},"itemCount":{"type":"integer","minimum":1}},"required":["txHash","totalAmountInUsdt","itemCount"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"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 v2 EOA"],"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","minimum":0,"exclusiveMinimum":true,"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":{"nullable":true}},"types":{"type":"object","additionalProperties":{"nullable":true}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{"nullable":true}}},"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 v2 EOA"],"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","minimum":0,"exclusiveMinimum":true,"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":{"nullable":true}},"types":{"type":"object","additionalProperties":{"nullable":true}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{"nullable":true}}},"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 v2 EOA"],"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","minimum":0,"exclusiveMinimum":true,"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":{"nullable":true}},"types":{"type":"object","additionalProperties":{"nullable":true}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{"nullable":true}}},"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 v2 EOA"],"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","minimum":0,"exclusiveMinimum":true,"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":{"nullable":true}},"types":{"type":"object","additionalProperties":{"nullable":true}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{"nullable":true}}},"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 v2 EOA"],"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 v2 EOA"],"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 v2 EOA"],"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 v2 EOA"],"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 v2 EOA"],"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":{"nullable":true}},"types":{"type":"object","additionalProperties":{"nullable":true}},"primaryType":{"type":"string"},"message":{"type":"object","additionalProperties":{"nullable":true}}},"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 v2 EOA"],"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/config":{"get":{"tags":["Marketplace v2"],"summary":"Get marketplace chain, token approvals and platform fee","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer"},"platformFeeBps":{"type":"integer","minimum":0,"maximum":10000},"contracts":{"type":"object","properties":{"nft":{"type":"string"},"usdt":{"type":"string"},"permit2":{"type":"string"},"orderbook":{"type":"string"}},"required":["nft","usdt","permit2","orderbook"]}},"required":["chainId","platformFeeBps","contracts"]}}}},"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":{"get":{"tags":["Marketplace v2"],"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","nullable":true,"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","nullable":true},"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 v2"],"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","nullable":true},"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","minimum":0,"exclusiveMinimum":true},"owner":{"type":"object","nullable":true,"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","nullable":true,"properties":{"value":{"type":"string"},"token":{"anyOf":[{"type":"string","enum":["USDT"]},{"type":"string","enum":["USD"]}]}},"required":["value","token"]},"last_sale":{"type":"object","nullable":true,"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 v2"],"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","nullable":true,"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/config":{"get":{"tags":["Redemption v2 EOA"],"security":[],"summary":"Get redemption contracts, card limit and shipping countries","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"walletSessionUri":{"type":"string","format":"uri","description":"Renaiss API wallet-session issuer. This is separate from the partner frontend origin in SIWE."},"chainId":{"type":"integer"},"tokenAddress":{"type":"string"},"permit2Address":{"type":"string"},"cashierAddress":{"type":"string"},"managerAddress":{"type":"string"},"maxCards":{"type":"integer"},"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"requiresState":{"type":"boolean"}},"required":["code","name","requiresState"]}}},"required":["walletSessionUri","chainId","tokenAddress","permit2Address","cashierAddress","managerAddress","maxCards","countries"]}}}},"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/cards":{"get":{"tags":["Redemption v2 EOA"],"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","nullable":true,"pattern":"^\\d{1,78}$"},"fmvUpdatedAt":{"type":"string","nullable":true,"format":"date-time"},"ownerAcquiredAt":{"type":"string","nullable":true,"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 v2 EOA"],"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 v2 EOA"],"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 v2 EOA"],"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","nullable":true},"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 v2 EOA"],"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":{"nullable":true}}},"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":{"nullable":true}}},"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 v2 EOA"],"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 v2 EOA"],"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 v2 EOA"],"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","nullable":true,"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","nullable":true},"shipmentStatus":{"type":"string","nullable":true},"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","nullable":true,"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 v2 EOA"],"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","nullable":true},"estimatedDeliveryDaysMax":{"type":"number","nullable":true},"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","nullable":true},"trackingUrl":{"type":"string","nullable":true},"shipmentStatus":{"type":"string","nullable":true},"shipmentProvider":{"type":"string","enum":["easyship","manual","cc"]},"trackingLastSyncedAt":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","nullable":true,"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","nullable":true,"pattern":"^\\d{1,78}$"},"fmvUpdatedAt":{"type":"string","nullable":true,"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 v2 EOA"],"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","nullable":true},"estimatedDeliveryDaysMax":{"type":"number","nullable":true},"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","nullable":true},"trackingUrl":{"type":"string","nullable":true},"shipmentStatus":{"type":"string","nullable":true},"shipmentProvider":{"type":"string","enum":["easyship","manual","cc"]},"trackingLastSyncedAt":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","nullable":true,"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","nullable":true,"pattern":"^\\d{1,78}$"},"fmvUpdatedAt":{"type":"string","nullable":true,"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"]}}}}}}}},"tags":[]}