{"openapi":"3.1.1","info":{"version":"1.0.0","title":"Renaiss API","description":"API documentation for Renaiss marketplace and services"},"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":{"User":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean","default":false,"readOnly":true},"image":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"role":{"type":"string","readOnly":true},"banned":{"type":"boolean","default":false,"readOnly":true},"banReason":{"type":"string","readOnly":true},"banExpires":{"type":"string","format":"date-time","readOnly":true},"walletAddress":{"type":"string"},"phoneNumber":{"type":"string"},"phoneVerifiedAt":{"type":"string","format":"date-time"},"phoneVerifiedVia":{"type":"string"},"twitterUsernameCache":{"type":"string"},"discordUsernameCache":{"type":"string"}},"required":["id","name","emailVerified","createdAt","updatedAt"]},"Session":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"expiresAt":{"type":"string","format":"date-time"},"token":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"ipAddress":{"type":"string"},"userAgent":{"type":"string"},"userId":{"type":"string"},"impersonatedBy":{"type":"string"},"authMethod":{"type":["siwe","privy"]},"geolocation":{"type":"json","readOnly":true},"twoFactorVerifiedAt":{"type":"string","format":"date-time","readOnly":true}},"required":["id","expiresAt","token","createdAt","updatedAt","userId","authMethod"]},"Account":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"accountId":{"type":"string"},"providerId":{"type":"string"},"userId":{"type":"string"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"idToken":{"type":"string"},"accessTokenExpiresAt":{"type":"string","format":"date-time"},"refreshTokenExpiresAt":{"type":"string","format":"date-time"},"scope":{"type":"string"},"password":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","accountId","providerId","userId","createdAt","updatedAt"]},"Verification":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"identifier":{"type":"string"},"value":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","identifier","value","expiresAt","createdAt","updatedAt"]},"WalletAddress":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"userId":{"type":"string"},"address":{"type":"string"},"chainId":{"type":"number"},"isPrimary":{"type":"boolean","default":false},"createdAt":{"type":"string","format":"date-time"},"kind":{"type":["siwe","privy"],"default":"siwe"}},"required":["id","userId","address","chainId","createdAt","kind"]},"Apikey":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"configId":{"type":"string","default":"default","readOnly":true},"name":{"type":"string","readOnly":true},"start":{"type":"string","readOnly":true},"referenceId":{"type":"string","readOnly":true},"prefix":{"type":"string","readOnly":true},"key":{"type":"string","readOnly":true},"refillInterval":{"type":"number","readOnly":true},"refillAmount":{"type":"number","readOnly":true},"lastRefillAt":{"type":"string","format":"date-time","readOnly":true},"enabled":{"type":"boolean","default":true,"readOnly":true},"rateLimitEnabled":{"type":"boolean","default":true,"readOnly":true},"rateLimitTimeWindow":{"type":"number","default":86400000,"readOnly":true},"rateLimitMax":{"type":"number","default":10,"readOnly":true},"requestCount":{"type":"number","default":0,"readOnly":true},"remaining":{"type":"number","readOnly":true},"lastRequest":{"type":"string","format":"date-time","readOnly":true},"expiresAt":{"type":"string","format":"date-time","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"permissions":{"type":"string","readOnly":true},"metadata":{"type":"string"}},"required":["id","configId","referenceId","key","createdAt","updatedAt"]},"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":{"/v0/cards/{tokenId}":{"get":{"tags":["Cards"],"summary":"Get card by token ID","description":"Returns public card data for CLI and detail views. Price details and activity history can be requested explicitly.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"tokenId","in":"path"},{"schema":{"type":"boolean"},"required":false,"name":"includeActivities","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"activitiesCursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"activitiesLimit","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"verbosePrice","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"collectible":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"pokemonName":{"type":"string"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"askPriceInUSDT":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-ASK-PRICE"]}]},"askExpiresAt":{"type":"string"},"fmvPriceInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-FMV-PRICE"]}]},"fmvUpdatedAt":{"type":"string","nullable":true},"frontImageUrl":{"type":"string","format":"uri"},"backImageUrl":{"type":"string","format":"uri"},"frontWithoutStandImageUrl":{"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},"custodyProvider":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"businessName":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["id","businessName","countryCode"]},"vaultRegionCountryCode":{"type":"string"},"owner":{"type":"object","nullable":true,"properties":{"username":{"type":"string"}},"required":["username"]}},"required":["tokenId","name","setName","cardNumber","pokemonName","ownerAddress","askPriceInUSDT","fmvPriceInUSD","fmvUpdatedAt","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"]}},"offers":{"type":"array","items":{"type":"object","properties":{"from":{"type":"object","properties":{"username":{"type":"string"},"address":{"type":"string"}},"required":["username","address"]},"timestamp":{"type":"string"},"amount":{"type":"object","properties":{"value":{"type":"string"},"token":{"anyOf":[{"type":"string","enum":["USDT"]},{"type":"string","enum":["USD"]}]}},"required":["value","token"]},"status":{"type":"string","enum":["accepted","waiting","expired"]},"expiresAt":{"type":"string"}},"required":["from","timestamp","amount","status","expiresAt"]}}},"required":["top_offer","last_sale"]},"activities":{"type":"object","nullable":true,"properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"tokenAmount":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["mint"]}},"required":["user","timestamp","blockNumber","txHash","tokenAmount","tokenId","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"tokenAmount":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["burn"]}},"required":["user","timestamp","blockNumber","txHash","tokenAmount","tokenId","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"to":{"type":"string"},"tokenId":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["transfer"]}},"required":["user","timestamp","blockNumber","txHash","to","tokenId","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^d+$"},"feeAccrued":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["sell"]}},"required":["user","timestamp","blockNumber","txHash","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued","type"]}]}},"nextCursor":{"type":"string","nullable":true}},"required":["activities","nextCursor"]}},"required":["collectible","pricing","activities"]}}}},"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"]}}}}}}},"/v0/config/contract-addresses":{"get":{"tags":["Config"],"summary":"Get contract addresses","description":"Returns public contract addresses that CLI clients need for onchain reads and signing flows.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"contractAddresses":{"type":"object","properties":{"nftAddress":{"type":"string"},"usdtAddress":{"type":"string"}},"required":["nftAddress","usdtAddress"]}},"required":["chainId","contractAddresses"]}}}},"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"]}}}}}}},"/v0/fair/packs":{"get":{"tags":["Fair"],"summary":"Pack directory for the fair verify site ","description":"Every pack with verifiable history (open, paused, or archived — never-opened packs are excluded). Shared by the Sets and Packing tabs; those endpoints require an onChainPackId from this list.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"packs":{"type":"array","items":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}},"imageUrl":{"type":"string"},"allCardDrawnSetCount":{"type":"integer"}},"required":["onChainPackId","vendingMachineAddress","name","tiers","imageUrl","allCardDrawnSetCount"]}}},"required":["packs"]}}}},"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"]}}}}}}},"/v0/fair/packs/{packId}/sets":{"get":{"tags":["Fair"],"summary":"Browse sets","description":"Paged sets of one pack for the public verifier: status, card count (completed sets only), and creation genesis. The lineup-derived data (Merkle root, cards with salts and draw proofs) is heavy and per-set — fetch it from /packs/{packId}/sets/{setId}.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":5},"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":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"sets":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["sold"]},"setId":{"type":"integer"},"cardCount":{"type":"integer"},"genesis":{"type":"object","nullable":true,"properties":{"algorithm":{"type":"string"},"attempts":{"type":"integer"},"triggerTime":{"type":"string"},"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["algorithm","attempts","triggerTime","blockNumber","blockHash","proof","publicKeyHex"]}},"required":["status","setId","cardCount","genesis"]},{"type":"object","properties":{"status":{"type":"string","enum":["active"]},"setId":{"type":"integer"},"packId":{"type":"string"},"merkleRoot":{"type":"string"},"algorithm":{"type":"string"}},"required":["status","setId","packId","merkleRoot","algorithm"]}]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["pack","sets","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack","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"]}}}}}}},"/v0/fair/packs/{packId}/packings":{"get":{"tags":["Fair"],"summary":"Browse set-creation runs","description":"Paged create-sub-pack run records of one pack: config, per-attempt outcomes, accepted set's Merkle root, and the creation VRF proof. Failed runs are served too — their rejection replays from the same proof. The token arrays (candidate pool + selected lineup) are heavy and only needed to replay one run — fetch them per run from /packings/{taskId}.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"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":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"packing":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["success"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true}},"required":["expectedValueInUsd","merkleRoot"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf"]},{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["failed"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true}},"required":["expectedValueInUsd","merkleRoot"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf"]},{"type":"object","properties":{"status":{"type":"string","enum":["active"]},"taskId":{"type":"string"},"setId":{"type":"integer"},"algorithm":{"type":"string"}},"required":["status","taskId","setId","algorithm"]}]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["pack","packing","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack","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"]}}}}}}},"/v0/fair/packs/{packId}/sets/{setId}":{"get":{"tags":["Fair"],"summary":"One set with full lineup and draw replay data","description":"Single set of a pack ({setId} from the sets list). A completed set serves every card with its formation-time value snapshot, Merkle salt, and draw proof, plus the availability root recomputed from the live lineup and the card display names. Sealed sets stay sealed: genesis only — no lineup, size, or root. All USD value fields are raw 2-implied-decimal integers.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0},"required":false,"name":"setId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"name":{"type":"string"},"setName":{"type":"string"},"displayName":{"type":"string"},"imageUrl":{"type":"string"}},"required":["tokenId","name","setName","displayName","imageUrl"]}},"set":{"type":"object","properties":{"setId":{"type":"integer"},"status":{"type":"string","enum":["completed","active","upcoming"]},"cardCount":{"type":"integer","nullable":true},"genesis":{"type":"object","nullable":true,"properties":{"algorithm":{"type":"string"},"attempts":{"type":"integer"},"triggerTime":{"type":"string"},"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["algorithm","attempts","triggerTime","blockNumber","blockHash","proof","publicKeyHex"]},"merkleRoot":{"type":"string","nullable":true},"cards":{"type":"array","nullable":true,"items":{"type":"object","properties":{"tokenId":{"type":"string"},"tier":{"type":"string","nullable":true},"valueInUsd":{"type":"integer"},"merkleSalt":{"type":"string"},"drawInfo":{"type":"object","nullable":true,"properties":{"checkoutId":{"type":"integer"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["checkoutId","blockHash","randomness","proof","publicKeyHex"]}},"required":["tokenId","tier","valueInUsd","merkleSalt","drawInfo"]}}},"required":["setId","status","cardCount","genesis","merkleRoot","cards"]}},"required":["pack","cards","set"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack or set","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"]}}}}}}},"/v0/fair/packings/{taskId}":{"get":{"tags":["Fair"],"summary":"One creation run with full selection replay data","description":"Single finished create-sub-pack run by taskId (from a pack's packings list): candidate pool in stored order, selected lineup with Merkle salts, card display names, and the creation VRF proof — everything a replay needs.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"taskId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"name":{"type":"string"},"setName":{"type":"string"},"displayName":{"type":"string"},"imageUrl":{"type":"string"}},"required":["tokenId","name","setName","displayName","imageUrl"]}},"run":{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["success","failed"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true},"tokens":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"valueInUsd":{"type":"integer"},"merkleSalt":{"type":"string","nullable":true}},"required":["tokenId","valueInUsd","merkleSalt"]}}},"required":["expectedValueInUsd","merkleRoot","tokens"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]},"inputTokens":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"valueInUsd":{"type":"integer"}},"required":["tokenId","valueInUsd"]}},"anchorTokenIds":{"type":"array","nullable":true,"items":{"type":"string"}}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf","inputTokens","anchorTokenIds"]}},"required":["pack","cards","run"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown or unfinished run","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"]}}}}}}},"/v0/fair/rips/{txHash}":{"get":{"tags":["Fair"],"summary":"Prove one rip from its permitFund transaction hash","description":"Single keyed lookup, served only once the tx's set is fully drawn (a rip from a still-active set returns 409 until then): every draw of the tx's batch with card, proof, and Merkle inclusion path (Tier A), plus the lineup token ids and all prior draws for a full index-resolution replay (Tier B).","parameters":[{"schema":{"type":"string"},"required":true,"name":"txHash","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"setId":{"type":"integer"},"setStatus":{"type":"string","enum":["active","completed"]},"merkleRoot":{"type":"string"},"draws":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"integer"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"},"card":{"type":"object","properties":{"tokenId":{"type":"string"},"tier":{"type":"string","nullable":true},"valueInUsd":{"type":"integer"},"merkleSalt":{"type":"string"},"name":{"type":"string"},"setName":{"type":"string"},"displayName":{"type":"string"},"imageUrl":{"type":"string"}},"required":["tokenId","tier","valueInUsd","merkleSalt","name","setName","displayName","imageUrl"]},"merkleProof":{"type":"array","items":{"type":"string"}}},"required":["checkoutId","blockHash","randomness","proof","publicKeyHex","card","merkleProof"]}},"replay":{"type":"object","properties":{"lineupTokenIds":{"type":"array","items":{"type":"string"}},"priorDraws":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"integer"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"}},"required":["checkoutId","blockHash","randomness","proof"]}}},"required":["lineupTokenIds","priorDraws"]}},"required":["pack","setId","setStatus","merkleRoot","draws","replay"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Set is not ready for verification, try again later","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"]}}}}}}},"/v0/gacha-v3/packs":{"get":{"tags":["Gacha"],"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":{"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__)"},"author":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^d+$"},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"featuredCardFmvInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"packBannerVideoUrl":{"type":"string","nullable":true},"gachaMachineVideoUrl":{"type":"string","nullable":true},"gachaRippingPackAnimationVideoUrl":{"type":"string","nullable":true}},"required":["slug","name","packType","stage","description","author","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd","packBannerVideoUrl","gachaMachineVideoUrl","gachaRippingPackAnimationVideoUrl"]}},"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"]}}}}}}},"/v0/gacha-v3/packs/{slug}":{"get":{"tags":["Gacha"],"summary":"Get VRF gacha pack by slug","description":"Returns public metadata for one VRF gacha pack, including pack and gacha machine video URLs.","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":{"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__)"},"author":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^d+$"},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"featuredCardFmvInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"packBannerVideoUrl":{"type":"string","nullable":true},"gachaMachineVideoUrl":{"type":"string","nullable":true},"gachaRippingPackAnimationVideoUrl":{"type":"string","nullable":true},"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"]}]}},"required":["tier","name","chance"]}}},"required":["slug","name","packType","stage","description","author","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd","packBannerVideoUrl","gachaMachineVideoUrl","gachaRippingPackAnimationVideoUrl","tiers"]}},"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"]}}}},"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"]}}}}}}},"/v0/gacha-v3/pull/prepare":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare VRF gacha pull signing data","description":"Authenticated API for preparing the unsigned VRF gacha pull payload and Permit2 witness typed data. The buyer Safe wallet is inferred from the API key session. Supply an optional bytes32 builderCode for on-chain attribution; omitted values use the zero bytes32 value.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"builderCode":{"type":"string","default":"0x0000000000000000000000000000000000000000000000000000000000000000"},"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}],"default":1},"permitDeadlineSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":300,"default":300},"packSlug":{"type":"string","minLength":1}},"required":["packSlug"]}}}},"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":{"pullStreamPath":{"type":"string","enum":["/v0/gacha-v3/pull/stream","/v1/gacha-v3/pull/stream"]}},"required":["pullStreamPath"]}]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","CARD_PACK_NOT_FOUND","CARD_PACK_NOT_ACTIVE","SAFE_ACCOUNT_NOT_FOUND","INSUFFICIENT_ALLOWANCE","GACHA_V3_PRICE_MISMATCH"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `CARD_PACK_NOT_FOUND`: Card pack not found\n- `CARD_PACK_NOT_ACTIVE`: Card pack is not active yet\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `INSUFFICIENT_ALLOWANCE`: Insufficient token allowance for Permit2\n- `GACHA_V3_PRICE_MISMATCH`: Signed amount does not match the current gacha v3 pack price"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":"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":{"code":{"type":"string","enum":["CARD_PACKS_QUERY_FAILED","GACHA_V3_VENDING_MACHINE_ADDRESS_NOT_FOUND","GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET","FUNCTION_ERROR"],"description":"Possible codes:\n- `CARD_PACKS_QUERY_FAILED`: Failed to query card packs\n- `GACHA_V3_VENDING_MACHINE_ADDRESS_NOT_FOUND`: Gacha v3 vending machine address not found for this pack\n- `GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET`: Gacha v3 pack has no onChainPackId set\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"]}}}}}}},"/v0/gacha-v3/pull/stream":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Open VRF gacha pack stream","description":"Authenticated Server-Sent Events endpoint for executing a signed VRF pull. Send the prepared unsignedPullPayload plus permitSignature. The stream emits start, permit-fund progress, open complete, and one aggregated draw-resolved complete event, then closes. Token release happens asynchronously after the buyback window.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"builderCode":{"type":"string","default":"0x0000000000000000000000000000000000000000000000000000000000000000"},"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},"permitSignature":{"type":"string"}},"required":["packId","numOfTokens","amountPerToken","nonce","deadline","permitSignature"]}}}},"responses":{"200":{"description":"Server-Sent Events stream","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":"API key required","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"]}}}}}}},"/v0/gacha-v3/draw-status":{"get":{"tags":["Gacha"],"security":[{"apiKeyAuth":[]}],"summary":"Recover VRF draw status","description":"Returns every resolved draw for one permit-fund transaction owned by the authenticated Safe wallet. Use this after an interrupted pull stream.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"cardPackId","in":"query"},{"schema":{"type":"string"},"required":true,"name":"permitFundTxHash","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"cardPackId":{"type":"string","format":"uuid"},"checkoutId":{"type":"integer","minimum":0},"permitFundTxHash":{"type":"string"},"settlementId":{"type":"string"},"collectibleTokenId":{"type":"string","pattern":"^\\d+$"},"collectible":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tokenId":{"type":"string","pattern":"^d+$"},"name":{"type":"string"},"itemId":{"type":"string","format":"uuid"},"buybackBaseValueInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-BUYBACK-BASE-VALUE"]}]},"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"]}]},"snapshotBuybackValueInUsdt":{"type":"string","nullable":true,"pattern":"^d+$"},"packDrawRecordId":{"type":"string","format":"uuid"}},"required":["id","tokenId","name","itemId","buybackBaseValueInUSD","frontImageUrl","imageUrl","tier","snapshotBuybackValueInUsdt","packDrawRecordId"]},"subpackDrawSequence":{"type":"string","pattern":"^\\d+$"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"},"status":{"type":"string","enum":["created","token-assigned","token-released","token-buybacked"]},"resolvedAt":{"type":"string"},"releaseTxHash":{"type":"string","nullable":true},"releaseTokenTxTimestamp":{"type":"string","nullable":true},"buybackTxHash":{"type":"string","nullable":true}},"required":["cardPackId","checkoutId","permitFundTxHash","settlementId","collectibleTokenId","collectible","subpackDrawSequence","blockHash","randomness","proof","status","resolvedAt","releaseTxHash","releaseTokenTxTimestamp","buybackTxHash"]}}}}},"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"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"No resolved draws found for this permit-fund transaction","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["GACHA_V3_DRAW_RECORD_NOT_FOUND"],"description":"Possible codes:\n- `GACHA_V3_DRAW_RECORD_NOT_FOUND`: No pack_draw_records row found for batch pull checkoutId"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["GACHA_V3_DRAW_STATUS_QUERY_FAILED","GACHA_V3_SUB_PACK_COLLECTIBLES_NOT_FOUND","COLLECTIBLE_NOT_FOUND"],"description":"Possible codes:\n- `GACHA_V3_DRAW_STATUS_QUERY_FAILED`: Failed to query gacha v3 draw status\n- `GACHA_V3_SUB_PACK_COLLECTIBLES_NOT_FOUND`: set collectibles not found\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/gacha-v3/buyback/offers":{"get":{"tags":["Gacha"],"security":[{"apiKeyAuth":[]}],"summary":"List available VRF buyback offers","description":"Authenticated API for listing VRF gacha buyback offers available to the current user. Wallet addresses are resolved from the API key session, including legacy and Safe addresses.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","maxLength":150},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"packSlug":{"type":"string"},"settlementId":{"type":"string"},"checkoutId":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"},"cardName":{"type":"string"},"setName":{"type":"string","nullable":true},"cardNumber":{"type":"string","nullable":true},"tier":{"type":"string","nullable":true},"frontImageUrl":{"type":"string","nullable":true},"buybackAmountInUsdt":{"type":"string","pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"vendingMachineAddress":{"type":"string"},"buybackAuthorization":{"type":"object","properties":{"buybackIds":{"type":"array","items":{"type":"string"},"minItems":1},"token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["buybackIds","token","amount"]}},"required":["packId","packSlug","settlementId","checkoutId","tokenId","cardName","setName","cardNumber","tier","frontImageUrl","buybackAmountInUsdt","buybackBaseValueInUsd","expiresAt","vendingMachineAddress","buybackAuthorization"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["offers","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"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["OFFER_QUERY_FAILED"],"description":"Possible codes:\n- `OFFER_QUERY_FAILED`: Failed to query offers"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/gacha-v3/buyback":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit VRF buyback","description":"Authenticated API for submitting a signed VRF buyback authorization. The buyer Safe wallet is inferred from the API key session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"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":["cardPackId","buybackAuth","userSignature"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED","GACHA_V3_TOKEN_STATUS_INVALID","GACHA_V3_BUYBACK_VERIFY_FAILED","GACHA_V3_BUYBACK_EXPIRED"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`: Failed to verify buyback authorization for perpetual gacha pack\n- `GACHA_V3_TOKEN_STATUS_INVALID`: token status is invalid\n- `GACHA_V3_BUYBACK_VERIFY_FAILED`: buyback owner does not match\n- `GACHA_V3_BUYBACK_EXPIRED`: buyback expired"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["PERPETUAL_GACHA_PACK_NOT_FOUND","GACHA_V3_DRAW_RECORD_NOT_FOUND"],"description":"Possible codes:\n- `PERPETUAL_GACHA_PACK_NOT_FOUND`: Perpetual gacha pack not found\n- `GACHA_V3_DRAW_RECORD_NOT_FOUND`: No pack_draw_records row found for batch pull checkoutId"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND","PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND","GACHA_V3_SETTLEMENT_ID_MISMATCH","COLLECTIBLE_NOT_FOUND","BUYBACK_BASE_VALUE_NOT_FOUND","GACHA_V3_BUYBACK_FAILED","GACHA_V3_TIMESTAMP_MISSING"],"description":"Possible codes:\n- `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND`: Perpetual gacha vending machine address not found for this pack\n- `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND`: Buyback config not found on this pack\n- `GACHA_V3_SETTLEMENT_ID_MISMATCH`: cached settlement id does not match its recomputed commitment\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUYBACK_BASE_VALUE_NOT_FOUND`: Buyback base value not found\n- `GACHA_V3_BUYBACK_FAILED`: Failed to perform gacha V3 buyback\n- `GACHA_V3_TIMESTAMP_MISSING`: Transaction mined but its block timestamp is missing"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/gacha/perpetual/pull/prepare":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare perpetual gacha pull signing data","description":"Authenticated API for preparing the unsigned perpetual gacha pull payload and Permit2 batch witness typed data. The buyer Safe wallet is inferred from the API key session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packSlug":{"type":"string","minLength":1},"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}],"default":1},"permitDeadlineSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":86400,"default":1800}},"required":["packSlug"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"pullPath":{"type":"string","enum":["/v0/gacha/perpetual/pull"]},"pack":{"type":"object","properties":{"id":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"vendingMachineAddress":{"type":"string"}},"required":["id","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":{"checkoutId":{"type":"string"},"numOfTokens":{"type":"string","pattern":"^\\d+$"}},"required":["checkoutId","numOfTokens"]}},"required":["permitted","spender","nonce","deadline","witness"]}},"required":["domain","types","primaryType","message"]},"unsignedPullPayload":{"type":"object","properties":{"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}]},"salt":{"type":"string","pattern":"^\\d+$"},"packId":{"type":"string","minLength":1},"buyerAuth":{"type":"object","properties":{"checkoutId":{"type":"string"},"buyer":{"type":"string"},"permitDeadline":{"type":"integer","minimum":0,"exclusiveMinimum":true},"token":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["checkoutId","buyer","permitDeadline","token","nonce","amount"]}},"required":["quantity","salt","packId","buyerAuth"]}},"required":["chainId","pullPath","pack","permit2TypedData","unsignedPullPayload"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"User and builder API keys required","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"]}}}}}}},"/v0/gacha/perpetual/pull":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Pull perpetual gacha packs","description":"Authenticated API for executing a signed perpetual gacha batch checkout payload. The buyer Safe wallet is inferred from the API key session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":10},"salt":{"type":"string","pattern":"^\\d+$"},"packId":{"type":"string","minLength":1},"buyerAuth":{"type":"object","properties":{"checkoutId":{"type":"string"},"buyer":{"type":"string"},"permitDeadline":{"type":"integer","minimum":0,"exclusiveMinimum":true},"token":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["checkoutId","buyer","permitDeadline","token","nonce","amount"]},"buyerPermit2Signature":{"type":"string"}},"required":["quantity","salt","packId","buyerAuth","buyerPermit2Signature"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"transactionHash":{"type":"string"},"batchCheckoutId":{"type":"string"},"checkoutIds":{"type":"array","items":{"type":"string"}},"tokenIds":{"type":"array","items":{"type":"string","pattern":"^d+$"}},"collectibles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tokenId":{"type":"string","pattern":"^d+$"},"name":{"type":"string"},"setName":{"type":"string"},"itemId":{"type":"string","format":"uuid"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"buybackBaseValueInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-BUYBACK-BASE-VALUE"]}]},"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"]}]},"frontImageUrl":{"type":"string","format":"uri"},"backImageUrl":{"type":"string","format":"uri"}},"required":["id","tokenId","name","setName","itemId","ownerAddress","buybackBaseValueInUSD","imageUrl","tier","frontImageUrl"]}},"pullResults":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"frontImageUrl":{"type":"string","format":"uri"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackAmountInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackAmountInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackExpiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["checkoutId","tokenId","name","setName","cardNumber","tier","frontImageUrl","fmvPriceInUsd","buybackBaseValueInUsd","buybackAmountInUsd","buybackAmountInUsdt","buybackExpiresAt"]}}},"required":["transactionHash","batchCheckoutId","checkoutIds","tokenIds","collectibles","pullResults"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"User and builder API keys required","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"]}}}}}}},"/v0/gacha/perpetual/buyback/prepare":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare perpetual buyback","description":"Authenticated API for preparing a sponsored Safe UserOperation and SafeOp typed data for perpetual buyback checkout records. The Safe and owner wallet addresses are inferred from the API key session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packSlug":{"type":"string","minLength":1},"checkoutIds":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["packSlug","checkoutIds"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"buybackAuths":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string","pattern":"^d+$"},"fmvInUsd":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"salt":{"type":"string"}},"required":["checkoutId","token","amount","fmvInUsd","tokenId","salt"]}},"oracleSignatures":{"type":"array","items":{"type":"string"}},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"verificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"preVerificationGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxPriorityFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterPostOpGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"safeOpTypedData":{"type":"object","properties":{"domain":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"verifyingContract":{"type":"string"}},"required":["chainId","verifyingContract"]},"types":{"type":"object","properties":{"SafeOp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"required":["SafeOp"]},"primaryType":{"type":"string","enum":["SafeOp"]},"message":{"type":"object","properties":{"safe":{"type":"string"},"callData":{"type":"string"},"nonce":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"initCode":{"type":"string"},"maxFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxPriorityFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"preVerificationGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"verificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"callGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterAndData":{"type":"string"},"validAfter":{"type":"integer","minimum":0},"validUntil":{"type":"integer","minimum":0},"entryPoint":{"type":"string"}},"required":["safe","callData","nonce","initCode","maxFeePerGas","maxPriorityFeePerGas","preVerificationGas","verificationGasLimit","callGasLimit","paymasterAndData","validAfter","validUntil","entryPoint"]}},"required":["domain","types","primaryType","message"]}},"required":["buybackAuths","oracleSignatures","sponsoredUserOperation","safeOpTypedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"User and builder API keys required","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"]}}}}}}},"/v0/gacha/perpetual/buyback/offers":{"get":{"tags":["Gacha"],"security":[{"apiKeyAuth":[]}],"summary":"List available perpetual buyback offers","description":"Authenticated API for listing perpetual gacha buyback offers available to the current user. Wallet addresses are resolved from the API key session, including legacy and Safe addresses.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["fmv","pullTime"],"default":"pullTime"},"required":false,"name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"maximum":500},"required":false,"name":"minFmvPercentage","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"packId":{"type":"string"},"packSlug":{"type":"string"},"checkoutId":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"},"cardName":{"type":"string"},"setName":{"type":"string","nullable":true},"cardNumber":{"type":"string","nullable":true},"tier":{"type":"string","nullable":true},"frontImageUrl":{"type":"string","nullable":true},"buybackAmountInUsd":{"type":"string","pattern":"^\\d+$"},"buybackAmountInUsdt":{"type":"string","pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["packId","packSlug","checkoutId","tokenId","cardName","setName","cardNumber","tier","frontImageUrl","buybackAmountInUsd","buybackAmountInUsdt","buybackBaseValueInUsd","expiresAt"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["offers","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/gacha/perpetual/buyback":{"post":{"tags":["Gacha"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Finalize perpetual buyback","description":"Authenticated API for submitting a signed sponsored Safe buyback UserOperation and syncing the resulting buyback records. The Safe and owner wallet addresses are inferred from the API key session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packSlug":{"type":"string","minLength":1},"ownerSignature":{"type":"string"},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"verificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"preVerificationGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxPriorityFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterPostOpGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"buybackAuths":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string","pattern":"^d+$"},"fmvInUsd":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"salt":{"type":"string"}},"required":["checkoutId","token","amount","fmvInUsd","tokenId","salt"]}},"oracleSignatures":{"type":"array","items":{"type":"string"}}},"required":["packSlug","ownerSignature","sponsoredUserOperation","buybackAuths","oracleSignatures"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string"},"userOperationHash":{"type":"string"}},"required":["txHash","userOperationHash"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"User and builder API keys required","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"]}}}}}}},"/v0/gacha/temporary/perpetual/pull/prepare":{"post":{"tags":["Gacha Temporary"],"summary":"Deprecated temporary: prepare perpetual gacha pull signing data","description":"Deprecated unauthenticated compatibility endpoint for old CLI clients. Use the authenticated /v0/gacha/perpetual/pull/prepare endpoint instead. This route prepares the unsigned perpetual gacha pull payload and Permit2 batch witness typed data. The client signs permit2TypedData, puts the signature into unsignedPullPayload.buyerPermit2Signature, then calls the temporary pull endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerWalletAddress":{"type":"string"},"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}],"default":1},"permitDeadlineSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":86400,"default":1800},"packSlug":{"type":"string","minLength":1}},"required":["buyerWalletAddress","packSlug"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"temporary":{"type":"boolean","enum":[true]},"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"pullPath":{"type":"string","enum":["/v0/gacha/temporary/perpetual/pull"]},"pack":{"type":"object","properties":{"id":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"vendingMachineAddress":{"type":"string"}},"required":["id","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":{"checkoutId":{"type":"string"},"numOfTokens":{"type":"string","pattern":"^\\d+$"}},"required":["checkoutId","numOfTokens"]}},"required":["permitted","spender","nonce","deadline","witness"]}},"required":["domain","types","primaryType","message"]},"unsignedPullPayload":{"type":"object","properties":{"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}]},"salt":{"type":"string","pattern":"^\\d+$"},"packId":{"type":"string","minLength":1},"buyerAuth":{"type":"object","properties":{"checkoutId":{"type":"string"},"buyer":{"type":"string"},"permitDeadline":{"type":"integer","minimum":0,"exclusiveMinimum":true},"token":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["checkoutId","buyer","permitDeadline","token","nonce","amount"]},"buyerWalletAddress":{"type":"string"}},"required":["quantity","salt","packId","buyerAuth","buyerWalletAddress"]}},"required":["temporary","chainId","pullPath","pack","permit2TypedData","unsignedPullPayload"]}}}},"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"]}}}}}}},"/v0/gacha/temporary/perpetual/pull":{"post":{"tags":["Gacha Temporary"],"summary":"Deprecated temporary: pull perpetual gacha packs","description":"Deprecated unauthenticated compatibility endpoint for old CLI clients. Use the authenticated /v0/gacha/perpetual/pull endpoint instead. This route executes the same signed perpetual gacha batch checkout payload used by web super mode. Use quantity 1 for a normal pull and 5 or 10 for super-mode pulls. The caller must provide buyerWalletAddress plus buyerAuth checkout fields and a batch Permit2 witness signature before calling this route. This route does not prepare or submit Safe/smart-wallet UserOps.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}]},"salt":{"type":"string","description":"string instead of bigint because tRPC SSE somehow cannot serialize bigint"},"packId":{"type":"string"},"buyerAuth":{"type":"object","properties":{"checkoutId":{"type":"string"},"buyer":{"type":"string"},"token":{"type":"string"},"permitDeadline":{"type":"number"},"nonce":{"type":"string","description":"string instead of bigint because tRPC SSE somehow cannot serialize bigint"},"amount":{"type":"string","description":"string instead of bigint because tRPC SSE somehow cannot serialize bigint"}},"required":["checkoutId","buyer","token","permitDeadline","nonce","amount"]},"buyerPermit2Signature":{"type":"string"},"buyerWalletAddress":{"type":"string"}},"required":["quantity","salt","packId","buyerAuth","buyerPermit2Signature","buyerWalletAddress"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"transactionHash":{"type":"string"},"batchCheckoutId":{"type":"string"},"checkoutIds":{"type":"array","items":{"type":"string"}},"tokenIds":{"type":"array","items":{"type":"string","pattern":"^d+$"}},"collectibles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tokenId":{"type":"string","pattern":"^d+$"},"name":{"type":"string"},"setName":{"type":"string"},"itemId":{"type":"string","format":"uuid"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"buybackBaseValueInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-BUYBACK-BASE-VALUE"]}]},"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"]}]},"frontImageUrl":{"type":"string","format":"uri"},"backImageUrl":{"type":"string","format":"uri"}},"required":["id","tokenId","name","setName","itemId","ownerAddress","buybackBaseValueInUSD","imageUrl","tier","frontImageUrl"]}},"pullResults":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"frontImageUrl":{"type":"string","format":"uri"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackAmountInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackAmountInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackExpiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["checkoutId","tokenId","name","setName","cardNumber","tier","frontImageUrl","fmvPriceInUsd","buybackBaseValueInUsd","buybackAmountInUsd","buybackAmountInUsdt","buybackExpiresAt"]}}},"required":["transactionHash","batchCheckoutId","checkoutIds","tokenIds","collectibles","pullResults"]}}}},"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"]}}}}}}},"/v0/gacha/temporary/perpetual/buyback/prepare":{"post":{"tags":["Gacha Temporary"],"summary":"Deprecated temporary: prepare perpetual buyback","description":"Deprecated unauthenticated compatibility endpoint for old CLI clients. Use the authenticated /v0/gacha/perpetual/buyback/prepare endpoint instead. This route prepares a sponsored Safe UserOperation and SafeOp typed data for perpetual buyback checkout records. The Safe owner signs the returned typed data and sends that signature to finalize.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packSlug":{"type":"string","minLength":1},"buyerWalletAddress":{"type":"string"},"ownerWalletAddress":{"type":"string"},"checkoutIds":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["packSlug","buyerWalletAddress","ownerWalletAddress","checkoutIds"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"buybackAuths":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string","pattern":"^d+$"},"fmvInUsd":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"salt":{"type":"string"}},"required":["checkoutId","token","amount","fmvInUsd","tokenId","salt"]}},"oracleSignatures":{"type":"array","items":{"type":"string"}},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^d+$"},"verificationGasLimit":{"type":"string","pattern":"^d+$"},"preVerificationGas":{"type":"string","pattern":"^d+$"},"maxFeePerGas":{"type":"string","pattern":"^d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"safeOpTypedData":{"type":"object","properties":{"domain":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"verifyingContract":{"type":"string"}},"required":["chainId","verifyingContract"]},"types":{"type":"object","properties":{"SafeOp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"required":["SafeOp"]},"primaryType":{"type":"string","enum":["SafeOp"]},"message":{"type":"object","properties":{"safe":{"type":"string"},"callData":{"type":"string"},"nonce":{"type":"string","pattern":"^d+$"},"initCode":{"type":"string"},"maxFeePerGas":{"type":"string","pattern":"^d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^d+$"},"preVerificationGas":{"type":"string","pattern":"^d+$"},"verificationGasLimit":{"type":"string","pattern":"^d+$"},"callGasLimit":{"type":"string","pattern":"^d+$"},"paymasterAndData":{"type":"string"},"validAfter":{"type":"integer","minimum":0},"validUntil":{"type":"integer","minimum":0},"entryPoint":{"type":"string"}},"required":["safe","callData","nonce","initCode","maxFeePerGas","maxPriorityFeePerGas","preVerificationGas","verificationGasLimit","callGasLimit","paymasterAndData","validAfter","validUntil","entryPoint"]}},"required":["domain","types","primaryType","message"]}},"required":["buybackAuths","oracleSignatures","sponsoredUserOperation","safeOpTypedData"]}}}},"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"]}}}}}}},"/v0/gacha/temporary/perpetual/buyback/finalize":{"post":{"tags":["Gacha Temporary"],"summary":"Deprecated temporary: finalize perpetual buyback","description":"Deprecated unauthenticated compatibility endpoint for old CLI clients. Use the authenticated /v0/gacha/perpetual/buyback endpoint instead. This route accepts the Safe owner signature for the prepared SafeOp, submits the sponsored UserOperation through the backend Pimlico/permissionless setup, then syncs the related records. The owning user is resolved from buyerWalletAddress.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packSlug":{"type":"string","minLength":1},"buyerWalletAddress":{"type":"string"},"ownerWalletAddress":{"type":"string"},"ownerSignature":{"type":"string"},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"verificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"preVerificationGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"maxPriorityFeePerGas":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterPostOpGasLimit":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"integer","minimum":0},{"type":"string","pattern":"^(0x[0-9a-fA-F]+|\\d+)$"}]},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"buybackAuths":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string","pattern":"^d+$"},"fmvInUsd":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"salt":{"type":"string"}},"required":["checkoutId","token","amount","fmvInUsd","tokenId","salt"]}},"oracleSignatures":{"type":"array","items":{"type":"string"}}},"required":["packSlug","buyerWalletAddress","ownerWalletAddress","ownerSignature","sponsoredUserOperation","buybackAuths","oracleSignatures"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string"},"userOperationHash":{"type":"string"}},"required":["txHash","userOperationHash"]}}}},"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 pack not found, or no user matches buyerWalletAddress","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"]}}}}}}},"/v0/gacha/packs":{"get":{"tags":["Gacha"],"summary":"List packs","description":"Returns public pack metadata for CLI consumers without pack contents","parameters":[{"schema":{"type":"boolean"},"required":false,"name":"includeInactive","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"cardPacks":{"type":"array","items":{"type":"object","properties":{"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__)"},"author":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^d+$"},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"featuredCardFmvInUsd":{"type":"string","nullable":true,"pattern":"^d+$"}},"required":["slug","name","packType","stage","description","author","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd"]}}},"required":["cardPacks"]}}}},"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"]}}}}}}},"/v0/gacha/packs/{slug}":{"get":{"tags":["Gacha"],"summary":"Get pack by slug","description":"Returns basic pack details. Perpetual packs include recent opened pack activity; pack contents are never returned.","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":{"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__)"},"author":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^d+$"},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"featuredCardFmvInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"packBannerVideoUrl":{"type":"string","nullable":true},"gachaMachineVideoUrl":{"type":"string","nullable":true},"gachaRippingPackAnimationVideoUrl":{"type":"string","nullable":true},"recentOpenedPacks":{"type":"array","nullable":true,"items":{"type":"object","properties":{"collectibleTokenId":{"type":"string","pattern":"^d+$"},"tier":{"type":"string"},"fmv":{"type":"string","pattern":"^d+$"},"pulledAtTimestamp":{"type":"number"}},"required":["collectibleTokenId","tier","fmv","pulledAtTimestamp"]}}},"required":["slug","name","packType","stage","description","author","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd","packBannerVideoUrl","gachaMachineVideoUrl","gachaRippingPackAnimationVideoUrl","recentOpenedPacks"]}},"required":["cardPack"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Pack 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"]}}}}}}},"/v0/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns a minimal serverless-friendly health status.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"timestamp":{"type":"string","format":"date-time"}},"required":["status","timestamp"]}}}}}}},"/v0/marketplace":{"get":{"tags":["Marketplace"],"summary":"List collectibles","description":"Returns a paginated list of collectibles with filtering and sorting options","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"includeAcquisition","in":"query"},{"schema":{"type":"string","enum":["POKEMON","ONE_PIECE"]},"required":false,"name":"categoryFilter","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"listedOnly","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":"boolean"},"required":false,"name":"favoritesFirst","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"string","enum":["fmvPriceInUsd","askPriceInUSDT","year","name","listDate","mintDate"],"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","pattern":"^d+$"},"name":{"type":"string"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"askPriceInUSDT":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-ASK-PRICE"]}]},"fmvPriceInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["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"]}}}}}}},"/v0/marketplace/cards/{tokenId}/orders":{"get":{"tags":["Marketplace"],"summary":"Get active marketplace orders for a 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+$"},"collectibleId":{"type":"string","format":"uuid"},"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","collectibleId","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"]}}}}}}},"/v0/marketplace/asks/prepare":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare ask typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"totalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"sellerReceivesInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}},"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"]}}}}}}},"/v0/marketplace/asks":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit signed ask","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"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/marketplace/asks/{tokenId}":{"delete":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Cancel active ask","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"tokenId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["cancel-ask","cancel-bid"]},"orderId":{"type":"string"},"collectibleId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CANCELLED"]}},"required":["operation","orderId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/marketplace/bids/prepare":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare bid typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId","amountInUsdt"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}},"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"]}}}}}}},"/v0/marketplace/bids":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit 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"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/marketplace/bids/{orderId}":{"delete":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Cancel outgoing bid","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orderId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["cancel-ask","cancel-bid"]},"orderId":{"type":"string"},"collectibleId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CANCELLED"]}},"required":["operation","orderId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/marketplace/buy/prepare":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare buy-now typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"expectedTotalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}},"409":{"description":"Ask price changed","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"]}}}}}}},"/v0/marketplace/buy":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit signed buy-now 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"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/marketplace/sell/prepare":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare accept-bid typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"bidOrderId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId","bidOrderId"]}}}},"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"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Bid or card not found","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"]}}}}}}},"/v0/marketplace/sell":{"post":{"tags":["Marketplace"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit signed accept-bid ask","requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"askSignature":{"type":"string"}},"required":["bidOrderId","collectibleId","askData","askSignature"]}}}},"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"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/wallets/permit2/usdt-approval/prepare":{"post":{"tags":["Wallets"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare sponsored Permit2 USDT approval","description":"Authenticated API for preparing a sponsored Safe UserOperation that approves Permit2 to spend USDT. The Safe and owner wallet addresses are inferred from the API key session.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["already_approved","needs_signature"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"},"deploymentStatus":{"type":"string","enum":["already_deployed","deployed"]},"deploymentTxHash":{"type":"string","nullable":true}},"required":["ownerWalletAddress","safeWalletAddress","deploymentStatus","deploymentTxHash"]},"approval":{"type":"object","properties":{"tokenAddress":{"type":"string"},"spenderAddress":{"type":"string"},"approvalAmount":{"type":"string","pattern":"^\\d+$"},"currentAllowance":{"type":"string","pattern":"^\\d+$"}},"required":["tokenAddress","spenderAddress","approvalAmount","currentAllowance"]},"sponsoredUserOperation":{"type":"object","nullable":true,"properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"safeOpTypedData":{"type":"object","nullable":true,"properties":{"domain":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"verifyingContract":{"type":"string"}},"required":["chainId","verifyingContract"]},"types":{"type":"object","properties":{"SafeOp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"required":["SafeOp"]},"primaryType":{"type":"string","enum":["SafeOp"]},"message":{"type":"object","properties":{"safe":{"type":"string"},"callData":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"initCode":{"type":"string"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterAndData":{"type":"string"},"validAfter":{"type":"integer","minimum":0},"validUntil":{"type":"integer","minimum":0},"entryPoint":{"type":"string"}},"required":["safe","callData","nonce","initCode","maxFeePerGas","maxPriorityFeePerGas","preVerificationGas","verificationGasLimit","callGasLimit","paymasterAndData","validAfter","validUntil","entryPoint"]}},"required":["domain","types","primaryType","message"]}},"required":["chainId","status","safe","approval","sponsoredUserOperation","safeOpTypedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/wallets/safe-deployment/prepare":{"post":{"tags":["Wallets"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare sponsored Safe deployment","description":"Authenticated API for preparing a sponsored Safe UserOperation that deploys the current user's deterministic Safe wallet when it is not already deployed.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["already_deployed","needs_signature"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"sponsoredUserOperation":{"type":"object","nullable":true,"properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"safeOpTypedData":{"type":"object","nullable":true,"properties":{"domain":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"verifyingContract":{"type":"string"}},"required":["chainId","verifyingContract"]},"types":{"type":"object","properties":{"SafeOp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"required":["SafeOp"]},"primaryType":{"type":"string","enum":["SafeOp"]},"message":{"type":"object","properties":{"safe":{"type":"string"},"callData":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"initCode":{"type":"string"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterAndData":{"type":"string"},"validAfter":{"type":"integer","minimum":0},"validUntil":{"type":"integer","minimum":0},"entryPoint":{"type":"string"}},"required":["safe","callData","nonce","initCode","maxFeePerGas","maxPriorityFeePerGas","preVerificationGas","verificationGasLimit","callGasLimit","paymasterAndData","validAfter","validUntil","entryPoint"]}},"required":["domain","types","primaryType","message"]}},"required":["chainId","status","safe","sponsoredUserOperation","safeOpTypedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/wallets/safe-deployment":{"post":{"tags":["Wallets"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit sponsored Safe deployment","description":"Authenticated API for submitting the signed sponsored Safe UserOperation returned by the Safe deployment prepare endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ownerSignature":{"type":"string"},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]}},"required":["ownerSignature","sponsoredUserOperation"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["deployed"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"userOperationHash":{"type":"string"},"transactionHash":{"type":"string"}},"required":["chainId","status","safe","userOperationHash","transactionHash"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","FUNCTION_ERROR","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `FUNCTION_ERROR`: Function error\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/wallets/permit2/usdt-approval":{"post":{"tags":["Wallets"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit sponsored Permit2 USDT approval","description":"Authenticated API for submitting the signed sponsored Safe UserOperation returned by the Permit2 USDT approval prepare endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ownerSignature":{"type":"string"},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]}},"required":["ownerSignature","sponsoredUserOperation"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["submitted"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"approval":{"type":"object","properties":{"tokenAddress":{"type":"string"},"spenderAddress":{"type":"string"},"approvalAmount":{"type":"string","pattern":"^\\d+$"},"currentAllowance":{"type":"string","pattern":"^\\d+$"}},"required":["tokenAddress","spenderAddress","approvalAmount","currentAllowance"]},"userOperationHash":{"type":"string"},"transactionHash":{"type":"string"}},"required":["chainId","status","safe","approval","userOperationHash","transactionHash"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","FUNCTION_ERROR","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `FUNCTION_ERROR`: Function error\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/users/me":{"get":{"tags":["Users"],"security":[{"apiKeyAuth":[]}],"summary":"Get current authenticated user","description":"Returns the authenticated API key user and wallet addresses used by CLI write flows.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"avatarUrl":{"type":"string","nullable":true}},"required":["id","username","avatarUrl"]},"wallets":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string","nullable":true}},"required":["ownerWalletAddress","safeWalletAddress"]}},"required":["user","wallets"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/users/me/activities":{"get":{"tags":["Users"],"security":[{"apiKeyAuth":[]}],"summary":"List current user's activities","description":"Returns on-chain activity for the authenticated user's resolved activity wallets, including legacy owner and Safe wallet history when available.","parameters":[{"schema":{"type":"string","enum":["all","pull","mint","burn","transfer","buyback","buy","sell","perp-pull","perp-buyback","perp-release-token","gacha-v3-pull","gacha-v3-buyback","gacha-v3-release-token","gacha-pull","gacha-buyback","gacha-release-token","limited-pull","limited-buyback","limited-mint","infinite-pull","infinite-buyback","infinite-release-token","gacha-v3-infinite-pull","gacha-v3-infinite-buyback","gacha-v3-infinite-release-token"],"default":"all"},"required":false,"name":"filter","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["pull"]},"checkoutId":{"type":"string"},"packId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","checkoutId","packId","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["mint"]},"tokenAmount":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","tokenAmount","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["burn"]},"tokenAmount":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","tokenAmount","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["transfer"]},"to":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","to","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["buyback"]},"checkoutId":{"type":"string"},"token":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","checkoutId","token","priceInUsdt","fmvPriceInUsd"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["buy"]},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"},"feeAccrued":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["sell"]},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"},"feeAccrued":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["sbt-mint"]}},"required":["user","timestamp","blockNumber","txHash","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-pull"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"numOfTokens":{"type":"integer"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-buyback"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","nftTokenId","priceInUsdt","fmvPriceInUsd"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-release-token"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","nftTokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-pull"]},"contractAddress":{"type":"string"},"packId":{"type":"string"},"token":{"type":"string"},"checkoutIds":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"totalAmount":{"type":"string","pattern":"^\\d+$"},"blockHash":{"type":"string"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","packId","token","checkoutIds","totalAmount","blockHash"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-buyback"]},"contractAddress":{"type":"string"},"buybackIds":{"type":"array","items":{"type":"string"}},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"token":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","buybackIds","token","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-release-token"]},"contractAddress":{"type":"string"},"releaseTokenId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","releaseTokenId","nftTokenId"]}]}},"nextCursor":{"type":"string","nullable":true}},"required":["activities","nextCursor"]}}}},"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"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["ACTIVITY_QUERY_FAILED"],"description":"Possible codes:\n- `ACTIVITY_QUERY_FAILED`: Failed to query activities"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v0/users/me/cards":{"get":{"tags":["Users"],"security":[{"apiKeyAuth":[]}],"summary":"List current user's cards","description":"Returns cards owned by the authenticated user's linked ownership wallets, including Safe and legacy addresses when available.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":15},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"string","enum":["fmvPriceInUsd","askPriceInUSDT","year","name","listDate","mintDate"],"default":"mintDate"},"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","pattern":"^\\d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"pokemonName":{"type":"string"},"ownerAddress":{"type":"string"},"askPriceInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"topBidPriceInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"frontImageUrl":{"type":"string","format":"uri"},"animationUrl":{"type":"string","nullable":true,"format":"uri"},"backImageUrl":{"type":"string","nullable":true,"format":"uri"},"frontWithoutStandImageUrl":{"type":"string","nullable":true,"format":"uri"},"attributes":{"type":"array","items":{"type":"object","properties":{"trait":{"type":"string"},"value":{"type":"string"}},"required":["trait","value"]}},"vaultLocation":{"type":"string","enum":["third-party","platform"]},"vaultProviderInfo":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"businessName":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["id","businessName","countryCode"]},"gradingCompany":{"type":"string"},"grade":{"type":"string"},"year":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tier":{"type":"string","nullable":true},"ownerAcquiredAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["tokenId","name","setName","cardNumber","pokemonName","ownerAddress","askPriceInUsdt","fmvPriceInUsd","buybackBaseValueInUsd","topBidPriceInUsdt","frontImageUrl","animationUrl","backImageUrl","frontWithoutStandImageUrl","attributes","vaultLocation","vaultProviderInfo","gradingCompany","grade","year","tier","ownerAcquiredAt"]}},"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"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/users/me/bids":{"get":{"tags":["Users"],"security":[{"apiKeyAuth":[]}],"summary":"List current user's outgoing bids","description":"Returns bids created by the authenticated user's linked wallets. Use bidId with DELETE /v0/marketplace/bids/{orderId} to cancel an active bid.","parameters":[{"schema":{"type":"string","enum":["active","expired","accepted","cancelled","all"],"default":"active"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","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"},{"schema":{"type":"string","enum":["fmv","pullTime"],"default":"pullTime"},"required":false,"name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"maximum":500},"required":false,"name":"minFmvPercentage","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"bids":{"type":"array","items":{"type":"object","properties":{"bidId":{"type":"string","format":"uuid"},"tokenId":{"type":"string","pattern":"^\\d+$"},"cardName":{"type":"string"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"status":{"type":"string","enum":["active","expired","accepted","cancelled"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"ownerAddress":{"type":"string"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"}},"required":["bidId","tokenId","cardName","amountInUsdt","status","expiresAt","createdAt","ownerAddress","fmvPriceInUsd"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["bids","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v0/users/{id}":{"get":{"tags":["Users"],"summary":"Get public user profile","description":"Returns public user profile with favorited collectibles and SBT badges.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"avatarUrl":{"type":"string"},"favoritedCollectibles":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^d+$"},"collectible":{"type":"object","nullable":true,"properties":{"item":{"type":"object","properties":{"setName":{"type":"string"},"name":{"type":"string"},"year":{"type":"number"},"cardNumber":{"type":"string"},"gradingCompany":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true}},"required":["setName","name","year","cardNumber","gradingCompany","grade"]},"gradingCompany":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"frontWithoutStandImageUrl":{"type":"string","nullable":true},"frontImageUrl":{"type":"string"}},"required":["item","gradingCompany","grade","fmvPriceInUsd","frontWithoutStandImageUrl","frontImageUrl"]}},"required":["tokenId","collectible"]}},"favoritedSBTs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"}},"required":["id","title","description","imageUrl"]}}},"required":["id","username","avatarUrl","favoritedCollectibles","favoritedSBTs"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"User 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"]}}}}}}},"/v0/users/{id}/binder":{"get":{"tags":["Binders"],"summary":"Get a user's public binder","description":"Returns the user's binder pages and placed items plus the cover (username, avatar). Each page carries its stable `id` so a frame/cupboard can be mapped to a specific page; `position` is display-order only and changes on reorder. Only filled pockets are returned. `card.tokenId` and `card.fmvPriceInUsd` are bigints serialized as decimal strings (`fmvPriceInUsd` is integer USD cents, null when no cached FMV exists). `owned` is false when the binder owner no longer holds the card — transferred away, burned, or never delivered — and is always true for badge slots (SBTs are soulbound); it is derived from the indexed chain mirror and served from cache, so it can trail an on-chain transfer by up to the cache lifetime below. A private or missing binder returns `404` and is not CDN-cached; public binders are cached.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"cover":{"type":"object","properties":{"username":{"type":"string"},"avatarUrl":{"type":"string","nullable":true},"address":{"type":"string"},"coverSource":{"type":"string","enum":["default","vinci_room"]}},"required":["username","avatarUrl","address","coverSource"]},"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"number"},"layout":{"type":"string","enum":["pocket_1","pocket_6","pocket_9"]},"slots":{"type":"array","items":{"type":"object","properties":{"slotIndex":{"type":"number"},"itemType":{"type":"string","enum":["collectible","sbt"]},"owned":{"type":"boolean"},"card":{"type":"object","nullable":true,"properties":{"tokenId":{"type":"string","pattern":"^d+$"},"name":{"type":"string","nullable":true},"setName":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"frontImageUrl":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true},"gradingCompany":{"type":"string","nullable":true},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^d+$"}},"required":["tokenId","name","setName","imageUrl","frontImageUrl","grade","gradingCompany","fmvPriceInUsd"]},"badge":{"type":"object","nullable":true,"properties":{"badgeId":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"howToEarn":{"type":"string"},"group":{"type":"string","nullable":true}},"required":["badgeId","name","description","imageUrl","howToEarn","group"]}},"required":["slotIndex","itemType","owned","card","badge"]}}},"required":["id","position","layout","slots"]}}},"required":["cover","pages"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Binder not found or not public","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"]}}}}}}},"/v1/user/me":{"get":{"tags":["Users v1"],"security":[{"apiKeyAuth":[]}],"summary":"Get current authenticated user","description":"Returns the authenticated API key user and wallet addresses used by CLI write flows.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"avatarUrl":{"type":"string","nullable":true}},"required":["id","username","avatarUrl"]},"wallets":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string","nullable":true}},"required":["ownerWalletAddress","safeWalletAddress"]}},"required":["user","wallets"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/user/me/activities":{"get":{"tags":["Users v1"],"security":[{"apiKeyAuth":[]}],"summary":"List current user's activities","description":"Returns on-chain activity for the authenticated user's resolved activity wallets, including legacy owner and Safe wallet history when available.","parameters":[{"schema":{"type":"string","enum":["all","pull","mint","burn","transfer","buyback","buy","sell","perp-pull","perp-buyback","perp-release-token","gacha-v3-pull","gacha-v3-buyback","gacha-v3-release-token","gacha-pull","gacha-buyback","gacha-release-token","limited-pull","limited-buyback","limited-mint","infinite-pull","infinite-buyback","infinite-release-token","gacha-v3-infinite-pull","gacha-v3-infinite-buyback","gacha-v3-infinite-release-token"],"default":"all"},"required":false,"name":"filter","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["pull"]},"checkoutId":{"type":"string"},"packId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","checkoutId","packId","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["mint"]},"tokenAmount":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","tokenAmount","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["burn"]},"tokenAmount":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","tokenAmount","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["transfer"]},"to":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","to","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["buyback"]},"checkoutId":{"type":"string"},"token":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","checkoutId","token","priceInUsdt","fmvPriceInUsd"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["buy"]},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"},"feeAccrued":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["sell"]},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"},"feeAccrued":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["sbt-mint"]}},"required":["user","timestamp","blockNumber","txHash","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-pull"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"numOfTokens":{"type":"integer"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-buyback"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","nftTokenId","priceInUsdt","fmvPriceInUsd"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-release-token"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","nftTokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-pull"]},"contractAddress":{"type":"string"},"packId":{"type":"string"},"token":{"type":"string"},"checkoutIds":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"totalAmount":{"type":"string","pattern":"^\\d+$"},"blockHash":{"type":"string"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","packId","token","checkoutIds","totalAmount","blockHash"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-buyback"]},"contractAddress":{"type":"string"},"buybackIds":{"type":"array","items":{"type":"string"}},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"token":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","buybackIds","token","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-release-token"]},"contractAddress":{"type":"string"},"releaseTokenId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","releaseTokenId","nftTokenId"]}]}},"nextCursor":{"type":"string","nullable":true}},"required":["activities","nextCursor"]}}}},"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"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["ACTIVITY_QUERY_FAILED"],"description":"Possible codes:\n- `ACTIVITY_QUERY_FAILED`: Failed to query activities"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/user/me/cards":{"get":{"tags":["Users v1"],"security":[{"apiKeyAuth":[]}],"summary":"List current user's cards","description":"Returns cards owned by the authenticated user's linked ownership wallets, including Safe and legacy addresses when available.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":15},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"string","enum":["fmvPriceInUsd","askPriceInUSDT","year","name","listDate","mintDate"],"default":"mintDate"},"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","pattern":"^\\d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"pokemonName":{"type":"string"},"ownerAddress":{"type":"string"},"askPriceInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"topBidPriceInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"frontImageUrl":{"type":"string","format":"uri"},"animationUrl":{"type":"string","nullable":true,"format":"uri"},"backImageUrl":{"type":"string","nullable":true,"format":"uri"},"frontWithoutStandImageUrl":{"type":"string","nullable":true,"format":"uri"},"attributes":{"type":"array","items":{"type":"object","properties":{"trait":{"type":"string"},"value":{"type":"string"}},"required":["trait","value"]}},"vaultLocation":{"type":"string","enum":["third-party","platform"]},"vaultProviderInfo":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"businessName":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["id","businessName","countryCode"]},"gradingCompany":{"type":"string"},"grade":{"type":"string"},"year":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tier":{"type":"string","nullable":true},"ownerAcquiredAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["tokenId","name","setName","cardNumber","pokemonName","ownerAddress","askPriceInUsdt","fmvPriceInUsd","buybackBaseValueInUsd","topBidPriceInUsdt","frontImageUrl","animationUrl","backImageUrl","frontWithoutStandImageUrl","attributes","vaultLocation","vaultProviderInfo","gradingCompany","grade","year","tier","ownerAcquiredAt"]}},"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"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v1/user/me/bids":{"get":{"tags":["Users v1"],"security":[{"apiKeyAuth":[]}],"summary":"List current user's outgoing bids","description":"Returns bids created by the authenticated user's linked wallets. Use bidId with DELETE /v1/marketplace/bids/{orderId} to cancel an active bid.","parameters":[{"schema":{"type":"string","enum":["active","expired","accepted","cancelled","all"],"default":"active"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","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"},{"schema":{"type":"string","enum":["fmv","pullTime"],"default":"pullTime"},"required":false,"name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"maximum":500},"required":false,"name":"minFmvPercentage","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"bids":{"type":"array","items":{"type":"object","properties":{"bidId":{"type":"string","format":"uuid"},"tokenId":{"type":"string","pattern":"^\\d+$"},"cardName":{"type":"string"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"status":{"type":"string","enum":["active","expired","accepted","cancelled"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"ownerAddress":{"type":"string"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"}},"required":["bidId","tokenId","cardName","amountInUsdt","status","expiresAt","createdAt","ownerAddress","fmvPriceInUsd"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["bids","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"401":{"description":"API key required","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"]}}}}}}},"/v1/user/me/pull-history":{"get":{"tags":["Users v1"],"security":[{"oauthAccessToken":[]}],"summary":"List the user's gacha pull history","description":"Every Gacha v3 card the authenticated user has drawn, newest first, with the tier of each card resolved against the tier ladder of the pack it came from.\n\nAuthenticated with a \"Sign in with Renaiss\" OAuth access token — `Authorization: Bearer <access_token>` — and requires the `gacha:read` scope, which the user grants on the consent screen. A user API key is NOT accepted here; this endpoint exists for partners acting on a user's behalf.\n\nTier is the reason this endpoint exists. It is deliberately absent from on-chain data (publishing it would let a bot infer what is left in the machine), so no subgraph query can reconstruct it and only a consented call can read it.\n\n`summary` carries counts per pack and tier for the same selection, so a campaign awarding rewards per tier never has to page through `pulls` at all.","parameters":[{"schema":{"type":"array","items":{"type":"string","minLength":1},"description":"Pack slug. Repeat (`?pack=a&pack=b`) or comma-separate to select several; omit for every pack."},"required":false,"name":"pack","in":"query"},{"schema":{"type":"array","items":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"description":"Tier name, exactly as a pack's ladder spells it (`D`…`TOP`, `C`…`legendary`, …). Repeat or comma-separate for several; omit for every tier. Values are OR'd with each other and AND'd with `pack`. A name that is not a tier on any pack is a 400; a tier that exists but not on a selected pack simply matches nothing."},"required":false,"name":"tier","in":"query"},{"schema":{"type":"string","nullable":true,"description":"Inclusive lower bound on pull time (ISO 8601), compared against the permit transaction's block time."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","nullable":true,"description":"Inclusive upper bound on pull time (ISO 8601), compared against the permit transaction's block time. A bare date (`2026-10-31`) means the end of that day in UTC, so the last day of a campaign is not silently excluded; pass a full timestamp for an exact bound."},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"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":{"pulls":{"type":"array","items":{"type":"object","properties":{"pack":{"type":"string","description":"Pack slug, the same identifier /v1/gacha-v3/packs/{slug} uses."},"packName":{"type":"string"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}],"description":"Tier of the pulled card WITHIN THIS PACK. Tier names are pack-relative — a limited pack runs D…TOP while a Renaiss perpetual pack runs C…legendary — so a tier only means something alongside its pack."},"tokenId":{"type":"string","pattern":"^\\d+$"},"checkoutId":{"type":"integer"},"pulledAt":{"type":"string","format":"date-time","description":"Block time of the permit transaction that funded the rip — the on-chain moment of the pull, verifiable on BscScan."},"releasedAt":{"type":"string","nullable":true,"format":"date-time"},"boughtBackAt":{"type":"string","nullable":true,"format":"date-time"},"status":{"type":"string","enum":["awaiting-release","delivered","bought-back"]}},"required":["pack","packName","tier","tokenId","checkoutId","pulledAt","releasedAt","boughtBackAt","status"]}},"summary":{"type":"array","items":{"type":"object","properties":{"pack":{"type":"string"},"packName":{"type":"string"},"tier":{"anyOf":[{"type":"string","enum":["TOP","S","A","B","C","D"]},{"type":"string","enum":["epic","rare","uncommon","common","legendary","thorn","bloom","crown"]}]},"count":{"type":"integer"}},"required":["pack","packName","tier","count"]},"description":"Counts per pack and tier for the selected packs and dates. Deliberately NOT narrowed by the `tier` filter, so one call gives the full breakdown a campaign needs without paging through the rows."},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]},"truncated":{"type":"boolean","description":"True when the account has more draws than one request will scan and the oldest were dropped. Narrow the date range if you ever see it."}},"required":["pulls","summary","pagination","truncated"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","CARD_PACK_NOT_FOUND"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\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"]}}}},"401":{"description":"OAuth access token missing, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["OAUTH_TOKEN_INVALID"],"description":"Possible codes:\n- `OAUTH_TOKEN_INVALID`: Invalid or expired OAuth access token"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"403":{"description":"The token does not carry the gacha:read scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["OAUTH_INSUFFICIENT_SCOPE"],"description":"Possible codes:\n- `OAUTH_INSUFFICIENT_SCOPE`: The access token does not grant the scope this endpoint requires"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"The consenting account has no Safe wallet yet","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"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":["GACHA_V3_PULL_HISTORY_QUERY_FAILED"],"description":"Possible codes:\n- `GACHA_V3_PULL_HISTORY_QUERY_FAILED`: Failed to read gacha pull history"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/user/{id}":{"get":{"tags":["Users v1"],"summary":"Get public user profile","description":"Returns public user profile with favorited collectibles and SBT badges.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"avatarUrl":{"type":"string"},"favoritedCollectibles":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^d+$"},"collectible":{"type":"object","nullable":true,"properties":{"item":{"type":"object","properties":{"setName":{"type":"string"},"name":{"type":"string"},"year":{"type":"number"},"cardNumber":{"type":"string"},"gradingCompany":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true}},"required":["setName","name","year","cardNumber","gradingCompany","grade"]},"gradingCompany":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"frontWithoutStandImageUrl":{"type":"string","nullable":true},"frontImageUrl":{"type":"string"}},"required":["item","gradingCompany","grade","fmvPriceInUsd","frontWithoutStandImageUrl","frontImageUrl"]}},"required":["tokenId","collectible"]}},"favoritedSBTs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"}},"required":["id","title","description","imageUrl"]}}},"required":["id","username","avatarUrl","favoritedCollectibles","favoritedSBTs"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"User 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"]}}}}}}},"/v1/users/{walletAddress}":{"get":{"tags":["Users v1"],"security":[{"builderAuth":[]}],"summary":"Get a user by wallet address","description":"Profile and wallet addresses for the user who owns this wallet. Either the owner wallet or the Safe resolves. Requires an approved builder API key. The user's own equivalent is /v1/user/me.","parameters":[{"schema":{"type":"string"},"required":true,"name":"walletAddress","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"avatarUrl":{"type":"string","nullable":true}},"required":["id","username","avatarUrl"]},"wallets":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string","nullable":true}},"required":["ownerWalletAddress","safeWalletAddress"]}},"required":["user","wallets"]}}}},"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"]}}}},"401":{"description":"Builder API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"No Renaiss account owns this wallet","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/users/{walletAddress}/cards":{"get":{"tags":["Users v1"],"security":[{"builderAuth":[]}],"summary":"List a user's cards","description":"Cards held by this user, including drawn-but-unreleased ones. Requires an approved builder API key. The user's own equivalent is /v1/user/me.","parameters":[{"schema":{"type":"string"},"required":true,"name":"walletAddress","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":15},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"string","enum":["fmvPriceInUsd","askPriceInUSDT","year","name","listDate","mintDate"],"default":"mintDate"},"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","pattern":"^\\d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"pokemonName":{"type":"string"},"ownerAddress":{"type":"string"},"askPriceInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"topBidPriceInUsdt":{"type":"string","nullable":true,"pattern":"^\\d+$"},"frontImageUrl":{"type":"string","format":"uri"},"animationUrl":{"type":"string","nullable":true,"format":"uri"},"backImageUrl":{"type":"string","nullable":true,"format":"uri"},"frontWithoutStandImageUrl":{"type":"string","nullable":true,"format":"uri"},"attributes":{"type":"array","items":{"type":"object","properties":{"trait":{"type":"string"},"value":{"type":"string"}},"required":["trait","value"]}},"vaultLocation":{"type":"string","enum":["third-party","platform"]},"vaultProviderInfo":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"businessName":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["id","businessName","countryCode"]},"gradingCompany":{"type":"string"},"grade":{"type":"string"},"year":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tier":{"type":"string","nullable":true},"ownerAcquiredAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["tokenId","name","setName","cardNumber","pokemonName","ownerAddress","askPriceInUsdt","fmvPriceInUsd","buybackBaseValueInUsd","topBidPriceInUsdt","frontImageUrl","animationUrl","backImageUrl","frontWithoutStandImageUrl","attributes","vaultLocation","vaultProviderInfo","gradingCompany","grade","year","tier","ownerAcquiredAt"]}},"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":{"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"]}}}},"401":{"description":"Builder API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"No Renaiss account owns this wallet","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"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":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/users/{walletAddress}/activities":{"get":{"tags":["Users v1"],"security":[{"builderAuth":[]}],"summary":"List a user's activities","description":"Public activity types only, and only the pulls this builder is attributed on. Mint, burn, transfer, buyback, release-token and SBT stay on /v1/user/me. Requires an approved builder API key. The user's own equivalent is /v1/user/me.","parameters":[{"schema":{"type":"string"},"required":true,"name":"walletAddress","in":"path"},{"schema":{"type":"string","enum":["all","pull","mint","burn","transfer","buyback","buy","sell","perp-pull","perp-buyback","perp-release-token","gacha-v3-pull","gacha-v3-buyback","gacha-v3-release-token","gacha-pull","gacha-buyback","gacha-release-token","limited-pull","limited-buyback","limited-mint","infinite-pull","infinite-buyback","infinite-release-token","gacha-v3-infinite-pull","gacha-v3-infinite-buyback","gacha-v3-infinite-release-token"],"default":"all"},"required":false,"name":"filter","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["pull"]},"checkoutId":{"type":"string"},"packId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","checkoutId","packId","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["mint"]},"tokenAmount":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","tokenAmount","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["burn"]},"tokenAmount":{"type":"string","pattern":"^\\d+$"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","tokenAmount","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["transfer"]},"to":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","to","tokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["buyback"]},"checkoutId":{"type":"string"},"token":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","checkoutId","token","priceInUsdt","fmvPriceInUsd"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["buy"]},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"},"feeAccrued":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["sell"]},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"},"feeAccrued":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["sbt-mint"]}},"required":["user","timestamp","blockNumber","txHash","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-pull"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"numOfTokens":{"type":"integer"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-buyback"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"},"fmvPriceInUsd":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","nftTokenId","priceInUsdt","fmvPriceInUsd"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["perp-release-token"]},"contractAddress":{"type":"string"},"checkoutId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","checkoutId","nftTokenId"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-pull"]},"contractAddress":{"type":"string"},"packId":{"type":"string"},"token":{"type":"string"},"checkoutIds":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"totalAmount":{"type":"string","pattern":"^\\d+$"},"blockHash":{"type":"string"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","packId","token","checkoutIds","totalAmount","blockHash"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-buyback"]},"contractAddress":{"type":"string"},"buybackIds":{"type":"array","items":{"type":"string"}},"nftTokenId":{"type":"string","pattern":"^\\d+$"},"token":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","buybackIds","token","priceInUsdt"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^\\d+$"},"blockNumber":{"type":"string","pattern":"^\\d+$"},"txHash":{"type":"string"},"item":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"imageUrl":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"}},"required":["tokenId","imageUrl","title","subtitle"]},"type":{"type":"string","enum":["gacha-v3-release-token"]},"contractAddress":{"type":"string"},"releaseTokenId":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^\\d+$"}},"required":["user","timestamp","blockNumber","txHash","type","contractAddress","releaseTokenId","nftTokenId"]}]}},"nextCursor":{"type":"string","nullable":true}},"required":["activities","nextCursor"]}}}},"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"]}}}},"401":{"description":"Builder API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"No Renaiss account owns this wallet","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"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":["ACTIVITY_QUERY_FAILED"],"description":"Possible codes:\n- `ACTIVITY_QUERY_FAILED`: Failed to query activities"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/users/{walletAddress}/bids":{"get":{"tags":["Users v1"],"security":[{"builderAuth":[]}],"summary":"List a user's outgoing bids","description":"Bids this user has placed, across every card. Requires an approved builder API key. The user's own equivalent is /v1/user/me.","parameters":[{"schema":{"type":"string"},"required":true,"name":"walletAddress","in":"path"},{"schema":{"type":"string","enum":["active","expired","accepted","cancelled","all"],"default":"active"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","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"},{"schema":{"type":"string","enum":["fmv","pullTime"],"default":"pullTime"},"required":false,"name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"maximum":500},"required":false,"name":"minFmvPercentage","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"bids":{"type":"array","items":{"type":"object","properties":{"bidId":{"type":"string","format":"uuid"},"tokenId":{"type":"string","pattern":"^\\d+$"},"cardName":{"type":"string"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"status":{"type":"string","enum":["active","expired","accepted","cancelled"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"ownerAddress":{"type":"string"},"fmvPriceInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"}},"required":["bidId","tokenId","cardName","amountInUsdt","status","expiresAt","createdAt","ownerAddress","fmvPriceInUsd"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["bids","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"]}}}},"401":{"description":"Builder API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"No Renaiss account owns this wallet","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"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":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/fair/packs":{"get":{"tags":["Fair"],"summary":"Pack directory for the fair verify site ","description":"Every pack with verifiable history (open, paused, or archived — never-opened packs are excluded). Shared by the Sets and Packing tabs; those endpoints require an onChainPackId from this list.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"packs":{"type":"array","items":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}},"imageUrl":{"type":"string"},"allCardDrawnSetCount":{"type":"integer"}},"required":["onChainPackId","vendingMachineAddress","name","tiers","imageUrl","allCardDrawnSetCount"]}}},"required":["packs"]}}}},"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"]}}}}}}},"/v1/fair/active-sets/{merkleRoot}":{"get":{"tags":["Fair"],"summary":"Resolve a merkle root to the set currently selling","description":"Single keyed lookup: which pack's ACTIVE set carries this availability merkle root. Answers only while the root is the live commitment — once a newer set supersedes it (or the set sells out) the lookup 404s, so a stale deep link goes nowhere rather than pointing at a set the lists no longer carry. The row is names-only: ids, root, and algorithm.","parameters":[{"schema":{"type":"string"},"required":true,"name":"merkleRoot","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"set":{"type":"object","properties":{"status":{"type":"string","enum":["active"]},"setId":{"type":"integer"},"packId":{"type":"string"},"merkleRoot":{"type":"string"},"algorithm":{"type":"string"}},"required":["status","setId","packId","merkleRoot","algorithm"]}},"required":["pack","set"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Not the active set root of any pack","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"]}}}}}}},"/v1/fair/packs/{packId}/sets":{"get":{"tags":["Fair"],"summary":"Browse sets","description":"Paged sets of one pack for the public verifier: status, card count (completed sets only), and creation genesis. The lineup-derived data (Merkle root, cards with salts and draw proofs) is heavy and per-set — fetch it from /packs/{packId}/sets/{setId}.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":5},"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":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"sets":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["sold"]},"setId":{"type":"integer"},"cardCount":{"type":"integer"},"genesis":{"type":"object","nullable":true,"properties":{"algorithm":{"type":"string"},"attempts":{"type":"integer"},"triggerTime":{"type":"string"},"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["algorithm","attempts","triggerTime","blockNumber","blockHash","proof","publicKeyHex"]}},"required":["status","setId","cardCount","genesis"]},{"type":"object","properties":{"status":{"type":"string","enum":["active"]},"setId":{"type":"integer"},"packId":{"type":"string"},"merkleRoot":{"type":"string"},"algorithm":{"type":"string"}},"required":["status","setId","packId","merkleRoot","algorithm"]}]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["pack","sets","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack","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"]}}}}}}},"/v1/fair/packs/{packId}/packings":{"get":{"tags":["Fair"],"summary":"Browse set-creation runs","description":"Paged by set, not by run: one entry per set (newest first), carrying the set's accepted creation run — config, per-attempt outcomes, Merkle root, and the creation VRF proof — plus totalFailCount, the number of failed runs that targeted the set. The failed runs themselves are served by /packs/{packId}/sets/{setId}/packings, and the heavy token arrays (candidate pool + selected lineup) per run by /packings/{taskId}.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"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":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"packing":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["success"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true}},"required":["expectedValueInUsd","merkleRoot"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]},"totalFailCount":{"type":"integer"}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf","totalFailCount"]},{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["failed"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true}},"required":["expectedValueInUsd","merkleRoot"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]},"totalFailCount":{"type":"integer"}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf","totalFailCount"]},{"type":"object","properties":{"status":{"type":"string","enum":["active"]},"taskId":{"type":"string"},"setId":{"type":"integer"},"algorithm":{"type":"string"}},"required":["status","taskId","setId","algorithm"]}]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["pack","packing","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack","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"]}}}}}}},"/v1/fair/packs/{packId}/sets/{setId}/packings":{"get":{"tags":["Fair"],"summary":"Browse one set's creation runs","description":"Paged create-sub-pack runs that targeted one set ({setId} from the sets list), newest first: the accepted run and every failed retry, in the same summary shape as the pack-level packings list. Filter with ?status=success|failed — with status=failed the pagination total is the set's fail count. The token arrays are heavy and only needed to replay one run — fetch them per run from /packings/{taskId}.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0},"required":false,"name":"setId","in":"path"},{"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"},{"schema":{"type":"string","enum":["success","failed"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"packing":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["success","failed"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true}},"required":["expectedValueInUsd","merkleRoot"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf"]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["pack","packing","pagination"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack or set","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"]}}}}}}},"/v1/fair/packs/{packId}/sets/{setId}":{"get":{"tags":["Fair"],"summary":"One set with full lineup and draw replay data","description":"Single set of a pack ({setId} from the sets list). A completed set serves every card with its formation-time value snapshot, Merkle salt, and draw proof, plus the availability root recomputed from the live lineup and the card display names. Sealed sets stay sealed: genesis only — no lineup, size, or root. All USD value fields are raw 2-implied-decimal integers.","parameters":[{"schema":{"type":"string"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0},"required":false,"name":"setId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"name":{"type":"string"},"setName":{"type":"string"},"displayName":{"type":"string"},"imageUrl":{"type":"string"}},"required":["tokenId","name","setName","displayName","imageUrl"]}},"set":{"type":"object","properties":{"setId":{"type":"integer"},"status":{"type":"string","enum":["completed","active","upcoming"]},"cardCount":{"type":"integer","nullable":true},"genesis":{"type":"object","nullable":true,"properties":{"algorithm":{"type":"string"},"attempts":{"type":"integer"},"triggerTime":{"type":"string"},"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["algorithm","attempts","triggerTime","blockNumber","blockHash","proof","publicKeyHex"]},"merkleRoot":{"type":"string","nullable":true},"cards":{"type":"array","nullable":true,"items":{"type":"object","properties":{"tokenId":{"type":"string"},"tier":{"type":"string","nullable":true},"valueInUsd":{"type":"integer"},"merkleSalt":{"type":"string"},"drawInfo":{"type":"object","nullable":true,"properties":{"checkoutId":{"type":"integer"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["checkoutId","blockHash","randomness","proof","publicKeyHex"]}},"required":["tokenId","tier","valueInUsd","merkleSalt","drawInfo"]}}},"required":["setId","status","cardCount","genesis","merkleRoot","cards"]}},"required":["pack","cards","set"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown pack or set","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"]}}}}}}},"/v1/fair/packings/{taskId}":{"get":{"tags":["Fair"],"summary":"One creation run with full selection replay data","description":"Single finished create-sub-pack run by taskId (from a pack's packings list): candidate pool in stored order, selected lineup with Merkle salts, card display names, and the creation VRF proof — everything a replay needs.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"taskId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"cards":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"name":{"type":"string"},"setName":{"type":"string"},"displayName":{"type":"string"},"imageUrl":{"type":"string"}},"required":["tokenId","name","setName","displayName","imageUrl"]}},"run":{"type":"object","properties":{"taskId":{"type":"string"},"setId":{"type":"integer"},"status":{"type":"string","enum":["success","failed"]},"triggerSource":{"type":"string","enum":["checkout","cron","manual"]},"algoUsed":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorDetail":{"type":"string","nullable":true},"startedAt":{"type":"string"},"finishedAt":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"config":{"type":"object","nullable":true,"properties":{"targetExpectedValueInUsd":{"type":"integer"},"lowerExpectedValueInUsd":{"type":"integer"},"upperExpectedValueInUsd":{"type":"integer"},"maxTokensInSet":{"type":"integer"},"lowerNumberOfTokensInNewSet":{"type":"integer"},"upperNumberOfTokensInNewSet":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"floorValueInUsd":{"type":"integer"},"minNumberOfTokens":{"type":"integer"},"maxNumberOfTokens":{"type":"integer"},"targetNumberOfTokensPercentage":{"type":"number"},"maxNumberOfTokensPercentage":{"type":"number"}},"required":["tier","floorValueInUsd","minNumberOfTokens","maxNumberOfTokens","targetNumberOfTokensPercentage"]}}}},"attempts":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string","enum":["success","error","invalid"]},"detail":{"type":"string","nullable":true},"durationMs":{"type":"number"},"ev":{"type":"integer","nullable":true},"drawStart":{"type":"integer"},"drawsUsed":{"type":"integer"}},"required":["outcome","detail","durationMs","ev","drawStart","drawsUsed"]}},"output":{"type":"object","nullable":true,"properties":{"expectedValueInUsd":{"type":"integer","nullable":true},"merkleRoot":{"type":"string","nullable":true},"tokens":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"valueInUsd":{"type":"integer"},"merkleSalt":{"type":"string","nullable":true}},"required":["tokenId","valueInUsd","merkleSalt"]}}},"required":["expectedValueInUsd","merkleRoot","tokens"]},"vrf":{"type":"object","nullable":true,"properties":{"blockNumber":{"type":"integer"},"blockHash":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"}},"required":["blockNumber","blockHash","proof","publicKeyHex"]},"inputTokens":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"string"},"valueInUsd":{"type":"integer"}},"required":["tokenId","valueInUsd"]}},"anchorTokenIds":{"type":"array","nullable":true,"items":{"type":"string"}}},"required":["taskId","setId","status","triggerSource","algoUsed","errorCode","errorDetail","startedAt","finishedAt","durationMs","config","attempts","output","vrf","inputTokens","anchorTokenIds"]}},"required":["pack","cards","run"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Unknown or unfinished run","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"]}}}}}}},"/v1/fair/rips/{txHash}":{"get":{"tags":["Fair"],"summary":"Prove one rip from its permitFund transaction hash","description":"Single keyed lookup, served only once the tx's set is fully drawn (a rip from a still-active set returns 409 until then): every draw of the tx's batch with card, proof, and Merkle inclusion path (Tier A), plus the lineup token ids and all prior draws for a full index-resolution replay (Tier B).","parameters":[{"schema":{"type":"string"},"required":true,"name":"txHash","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"object","properties":{"onChainPackId":{"type":"string"},"vendingMachineAddress":{"type":"string"},"name":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"name":{"type":"string"}},"required":["tier","name"]}}},"required":["onChainPackId","vendingMachineAddress","name","tiers"]},"setId":{"type":"integer"},"setStatus":{"type":"string","enum":["active","completed"]},"merkleRoot":{"type":"string"},"draws":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"integer"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"},"publicKeyHex":{"type":"string"},"card":{"type":"object","properties":{"tokenId":{"type":"string"},"tier":{"type":"string","nullable":true},"valueInUsd":{"type":"integer"},"merkleSalt":{"type":"string"},"name":{"type":"string"},"setName":{"type":"string"},"displayName":{"type":"string"},"imageUrl":{"type":"string"}},"required":["tokenId","tier","valueInUsd","merkleSalt","name","setName","displayName","imageUrl"]},"merkleProof":{"type":"array","items":{"type":"string"}}},"required":["checkoutId","blockHash","randomness","proof","publicKeyHex","card","merkleProof"]}},"replay":{"type":"object","properties":{"lineupTokenIds":{"type":"array","items":{"type":"string"}},"priorDraws":{"type":"array","items":{"type":"object","properties":{"checkoutId":{"type":"integer"},"blockHash":{"type":"string"},"randomness":{"type":"string"},"proof":{"type":"string"}},"required":["checkoutId","blockHash","randomness","proof"]}}},"required":["lineupTokenIds","priorDraws"]}},"required":["pack","setId","setStatus","merkleRoot","draws","replay"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"409":{"description":"Set is not ready for verification, try again later","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"]}}}}}}},"/v1/gacha-v3/packs":{"get":{"tags":["Gacha v1"],"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__)"},"author":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^d+$"},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"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","author","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"]}}}}}}},"/v1/gacha-v3/packs/{slug}/pull-history":{"get":{"tags":["Gacha v1"],"summary":"Get VRF gacha pack pull history","description":"Returns cards that have already left this pack, newest first, with the pack-wide buyback window available from GET /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"]}}}}}}},"/v1/gacha-v3/packs/{slug}":{"get":{"tags":["Gacha v1"],"summary":"Get VRF gacha pack by slug","description":"Returns public metadata for one VRF gacha pack, including pack and gacha machine video URLs.","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__)"},"author":{"type":"string"},"priceInUsdt":{"type":"string","pattern":"^d+$"},"expectedValueInUsd":{"type":"string","nullable":true,"pattern":"^d+$"},"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"]}]}},"required":["tier","name","chance"]}},"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","author","priceInUsdt","expectedValueInUsd","featuredCardFmvInUsd","packBannerVideoUrl","gachaMachineVideoUrl","gachaRippingPackAnimationVideoUrl","onChainPackId","vendingMachineAddress","tiers","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"]}}}},"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"]}}}}}}},"/v1/gacha-v3/pull/prepare":{"post":{"tags":["Gacha v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Prepare VRF gacha pull signing data","description":"Authenticated API for preparing the unsigned VRF gacha pull payload and Permit2 witness typed data. The buyer Safe wallet comes from the API key session, or from `buyerWalletAddress` when authorizing with a builder API key. Supply an optional bytes32 builderCode for on-chain attribution; omitted values use the zero bytes32 value.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"builderCode":{"type":"string","default":"0x0000000000000000000000000000000000000000000000000000000000000000"},"quantity":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[5]},{"type":"number","enum":[10]}],"default":1},"permitDeadlineSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":300,"default":300},"packSlug":{"type":"string","minLength":1},"buyerWalletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}},"required":["packSlug"]}}}},"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":{"pullStreamPath":{"type":"string","enum":["/v0/gacha-v3/pull/stream","/v1/gacha-v3/pull/stream"]}},"required":["pullStreamPath"]}]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","CARD_PACK_NOT_FOUND","CARD_PACK_NOT_ACTIVE","SAFE_ACCOUNT_NOT_FOUND","INSUFFICIENT_ALLOWANCE","GACHA_V3_PRICE_MISMATCH"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `CARD_PACK_NOT_FOUND`: Card pack not found\n- `CARD_PACK_NOT_ACTIVE`: Card pack is not active yet\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `INSUFFICIENT_ALLOWANCE`: Insufficient token allowance for Permit2\n- `GACHA_V3_PRICE_MISMATCH`: Signed amount does not match the current gacha v3 pack price"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `CARD_PACK_NOT_FOUND`: Card pack not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["CARD_PACKS_QUERY_FAILED","GACHA_V3_VENDING_MACHINE_ADDRESS_NOT_FOUND","GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET","FUNCTION_ERROR"],"description":"Possible codes:\n- `CARD_PACKS_QUERY_FAILED`: Failed to query card packs\n- `GACHA_V3_VENDING_MACHINE_ADDRESS_NOT_FOUND`: Gacha v3 vending machine address not found for this pack\n- `GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET`: Gacha v3 pack has no onChainPackId set\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"]}}}}}}},"/v1/gacha-v3/pull/stream":{"post":{"tags":["Gacha v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Open VRF gacha pack stream","description":"Authenticated Server-Sent Events endpoint for executing a signed VRF pull. Send the prepared unsignedPullPayload plus permitSignature. The stream emits start, permit-fund progress, open complete, and one aggregated draw-resolved complete event, then closes. Token release happens asynchronously after the buyback window.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"builderCode":{"type":"string","default":"0x0000000000000000000000000000000000000000000000000000000000000000"},"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},"permitSignature":{"type":"string"},"buyerWalletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}},"required":["packId","numOfTokens","amountPerToken","nonce","deadline","permitSignature"]}}}},"responses":{"200":{"description":"Server-Sent Events stream","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":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error","code"]}}}},"404":{"description":"Buyer wallet has no Renaiss account","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"]}}}}}}},"/v1/gacha-v3/buyback/offers":{"get":{"tags":["Gacha v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"List available VRF buyback offers","description":"Authenticated API for listing VRF gacha buyback offers available to the current user. Wallet addresses are resolved from the API key session, including legacy and Safe addresses.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."},"required":false,"description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves.","name":"buyerWalletAddress","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"packSlug":{"type":"string"},"settlementId":{"type":"string"},"checkoutId":{"type":"string"},"tokenId":{"type":"string","pattern":"^\\d+$"},"cardName":{"type":"string"},"setName":{"type":"string","nullable":true},"cardNumber":{"type":"string","nullable":true},"tier":{"type":"string","nullable":true},"frontImageUrl":{"type":"string","nullable":true},"buybackAmountInUsdt":{"type":"string","pattern":"^\\d+$"},"buybackBaseValueInUsd":{"type":"string","nullable":true,"pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"vendingMachineAddress":{"type":"string"},"buybackAuthorization":{"type":"object","properties":{"buybackIds":{"type":"array","items":{"type":"string"},"minItems":1},"token":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["buybackIds","token","amount"]}},"required":["packId","packSlug","settlementId","checkoutId","tokenId","cardName","setName","cardNumber","tier","frontImageUrl","buybackAmountInUsdt","buybackBaseValueInUsd","expiresAt","vendingMachineAddress","buybackAuthorization"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["offers","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"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["OFFER_QUERY_FAILED"],"description":"Possible codes:\n- `OFFER_QUERY_FAILED`: Failed to query offers"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/gacha-v3/buyback":{"post":{"tags":["Gacha v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Submit VRF buyback","description":"Authenticated API for submitting a signed VRF buyback authorization. The buyer Safe wallet comes from the API key session, or from `buyerWalletAddress` when authorizing with a builder API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"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"},"buyerWalletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}},"required":["cardPackId","buybackAuth","userSignature"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED","GACHA_V3_TOKEN_STATUS_INVALID","GACHA_V3_BUYBACK_VERIFY_FAILED","GACHA_V3_BUYBACK_EXPIRED"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`: Failed to verify buyback authorization for perpetual gacha pack\n- `GACHA_V3_TOKEN_STATUS_INVALID`: token status is invalid\n- `GACHA_V3_BUYBACK_VERIFY_FAILED`: buyback owner does not match\n- `GACHA_V3_BUYBACK_EXPIRED`: buyback expired"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["PERPETUAL_GACHA_PACK_NOT_FOUND","GACHA_V3_DRAW_RECORD_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `PERPETUAL_GACHA_PACK_NOT_FOUND`: Perpetual gacha pack not found\n- `GACHA_V3_DRAW_RECORD_NOT_FOUND`: No pack_draw_records row found for batch pull checkoutId\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND","PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND","GACHA_V3_SETTLEMENT_ID_MISMATCH","COLLECTIBLE_NOT_FOUND","BUYBACK_BASE_VALUE_NOT_FOUND","GACHA_V3_BUYBACK_FAILED","GACHA_V3_TIMESTAMP_MISSING"],"description":"Possible codes:\n- `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND`: Perpetual gacha vending machine address not found for this pack\n- `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND`: Buyback config not found on this pack\n- `GACHA_V3_SETTLEMENT_ID_MISMATCH`: cached settlement id does not match its recomputed commitment\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUYBACK_BASE_VALUE_NOT_FOUND`: Buyback base value not found\n- `GACHA_V3_BUYBACK_FAILED`: Failed to perform gacha V3 buyback\n- `GACHA_V3_TIMESTAMP_MISSING`: Transaction mined but its block timestamp is missing"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/wallets/permit2/usdt-approval/prepare":{"post":{"tags":["Wallets v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Prepare sponsored Permit2 USDT approval","description":"Authenticated API for preparing a sponsored Safe UserOperation that approves Permit2 to spend USDT. The Safe and owner wallet addresses come from the API key session, or from `walletAddress` when authorizing with a builder API key.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["already_approved","needs_signature"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"approval":{"type":"object","properties":{"tokenAddress":{"type":"string"},"spenderAddress":{"type":"string"},"approvalAmount":{"type":"string","pattern":"^\\d+$"},"currentAllowance":{"type":"string","pattern":"^\\d+$"}},"required":["tokenAddress","spenderAddress","approvalAmount","currentAllowance"]},"sponsoredUserOperation":{"type":"object","nullable":true,"properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"safeOpTypedData":{"type":"object","nullable":true,"properties":{"domain":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"verifyingContract":{"type":"string"}},"required":["chainId","verifyingContract"]},"types":{"type":"object","properties":{"SafeOp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"required":["SafeOp"]},"primaryType":{"type":"string","enum":["SafeOp"]},"message":{"type":"object","properties":{"safe":{"type":"string"},"callData":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"initCode":{"type":"string"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterAndData":{"type":"string"},"validAfter":{"type":"integer","minimum":0},"validUntil":{"type":"integer","minimum":0},"entryPoint":{"type":"string"}},"required":["safe","callData","nonce","initCode","maxFeePerGas","maxPriorityFeePerGas","preVerificationGas","verificationGasLimit","callGasLimit","paymasterAndData","validAfter","validUntil","entryPoint"]}},"required":["domain","types","primaryType","message"]}},"required":["chainId","status","safe","approval","sponsoredUserOperation","safeOpTypedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/wallets/safe-deployment/prepare":{"post":{"tags":["Wallets v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Prepare sponsored Safe deployment","description":"Authenticated API for preparing a sponsored Safe UserOperation that deploys the deterministic Safe wallet of the user named by the API key session, or by `walletAddress` when authorizing with a builder API key, when it is not already deployed.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["already_deployed","needs_signature"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"sponsoredUserOperation":{"type":"object","nullable":true,"properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"safeOpTypedData":{"type":"object","nullable":true,"properties":{"domain":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"verifyingContract":{"type":"string"}},"required":["chainId","verifyingContract"]},"types":{"type":"object","properties":{"SafeOp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"]}}},"required":["SafeOp"]},"primaryType":{"type":"string","enum":["SafeOp"]},"message":{"type":"object","properties":{"safe":{"type":"string"},"callData":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"initCode":{"type":"string"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterAndData":{"type":"string"},"validAfter":{"type":"integer","minimum":0},"validUntil":{"type":"integer","minimum":0},"entryPoint":{"type":"string"}},"required":["safe","callData","nonce","initCode","maxFeePerGas","maxPriorityFeePerGas","preVerificationGas","verificationGasLimit","callGasLimit","paymasterAndData","validAfter","validUntil","entryPoint"]}},"required":["domain","types","primaryType","message"]}},"required":["chainId","status","safe","sponsoredUserOperation","safeOpTypedData"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/wallets/safe-deployment":{"post":{"tags":["Wallets v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Submit sponsored Safe deployment","description":"Authenticated API for submitting the signed sponsored Safe UserOperation returned by the Safe deployment prepare endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ownerSignature":{"type":"string"},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"walletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}},"required":["ownerSignature","sponsoredUserOperation"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["deployed"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"userOperationHash":{"type":"string"},"transactionHash":{"type":"string"}},"required":["chainId","status","safe","userOperationHash","transactionHash"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","FUNCTION_ERROR","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `FUNCTION_ERROR`: Function error\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/wallets/permit2/usdt-approval":{"post":{"tags":["Wallets v1"],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[],"builderAuth":[]},{"builderAuth":[]}],"summary":"Submit sponsored Permit2 USDT approval","description":"Authenticated API for submitting the signed sponsored Safe UserOperation returned by the Permit2 USDT approval prepare endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ownerSignature":{"type":"string"},"sponsoredUserOperation":{"type":"object","properties":{"sender":{"type":"string"},"nonce":{"type":"string","pattern":"^\\d+$"},"factory":{"type":"string"},"factoryData":{"type":"string"},"callData":{"type":"string"},"callGasLimit":{"type":"string","pattern":"^\\d+$"},"verificationGasLimit":{"type":"string","pattern":"^\\d+$"},"preVerificationGas":{"type":"string","pattern":"^\\d+$"},"maxFeePerGas":{"type":"string","pattern":"^\\d+$"},"maxPriorityFeePerGas":{"type":"string","pattern":"^\\d+$"},"paymaster":{"type":"string"},"paymasterVerificationGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterPostOpGasLimit":{"type":"string","pattern":"^\\d+$"},"paymasterData":{"type":"string"},"signature":{"type":"string"}},"required":["sender","nonce","callData","callGasLimit","verificationGasLimit","preVerificationGas","maxFeePerGas","maxPriorityFeePerGas"]},"walletAddress":{"type":"string","description":"The wallet this request acts for. Required when authorizing with x-builder-api-key alone, and ignored when the caller sends their own x-api-key, which already names the subject. Either the owner wallet or the Safe resolves."}},"required":["ownerSignature","sponsoredUserOperation"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"status":{"type":"string","enum":["submitted"]},"safe":{"type":"object","properties":{"ownerWalletAddress":{"type":"string"},"safeWalletAddress":{"type":"string"}},"required":["ownerWalletAddress","safeWalletAddress"]},"approval":{"type":"object","properties":{"tokenAddress":{"type":"string"},"spenderAddress":{"type":"string"},"approvalAmount":{"type":"string","pattern":"^\\d+$"},"currentAllowance":{"type":"string","pattern":"^\\d+$"}},"required":["tokenAddress","spenderAddress","approvalAmount","currentAllowance"]},"userOperationHash":{"type":"string"},"transactionHash":{"type":"string"}},"required":["chainId","status","safe","approval","userOperationHash","transactionHash"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","FUNCTION_ERROR","INSUFFICIENT_USDT_AMOUNT"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `FUNCTION_ERROR`: Function error\n- `INSUFFICIENT_USDT_AMOUNT`: You don't have enough USDT to complete this purchase. Top up your balance and try again."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR","GET_BALANCE_ERROR"],"description":"Possible codes:\n- `FUNCTION_ERROR`: Function error\n- `GET_BALANCE_ERROR`: Unexpected error during wallet balance retrieval"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}}}}},"/v1/marketplace":{"get":{"tags":["Marketplace v1"],"summary":"List collectibles","description":"Returns a paginated list of collectibles with filtering and sorting options","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":150},"required":false,"name":"search","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"includeAcquisition","in":"query"},{"schema":{"type":"string","enum":["POKEMON","ONE_PIECE"]},"required":false,"name":"categoryFilter","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"listedOnly","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":"boolean"},"required":false,"name":"favoritesFirst","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"string","enum":["fmvPriceInUsd","askPriceInUSDT","year","name","listDate","mintDate"],"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","pattern":"^d+$"},"name":{"type":"string"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"askPriceInUSDT":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-ASK-PRICE"]}]},"fmvPriceInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["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":{"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":["USER_NOT_FOUND"],"description":"Possible codes:\n- `USER_NOT_FOUND`: User 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":"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":{"code":{"type":"string","enum":["ALL_COLLECTIBLES_QUERY_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `ALL_COLLECTIBLES_QUERY_FAILED`: Failed to query all collectibles\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"]}}}}}}},"/v1/marketplace/cards/{tokenId}/orders":{"get":{"tags":["Marketplace v1"],"summary":"Get active marketplace orders for a 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+$"},"collectibleId":{"type":"string","format":"uuid"},"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","collectibleId","activeAsk","activeBids"]}}}},"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":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["COLLECTIBLE_NOT_FOUND"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible 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":"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":{"code":{"type":"string","enum":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/marketplace/asks/prepare":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare ask typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"totalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"sellerReceivesInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","WRONG_REQUEST_PARAMS"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["COLLECTIBLE_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/marketplace/asks":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit signed ask","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"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","INVALID_ASK_SIGNATURE","ASK_HAS_ALREADY_EXPIRED","ASK_TOKEN_ID_MISMATCH","COLLECTIBLE_ONCHAIN_OWNER_MISMATCH"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `INVALID_ASK_SIGNATURE`: Ask signature is invalid\n- `ASK_HAS_ALREADY_EXPIRED`: Ask has already expired\n- `ASK_TOKEN_ID_MISMATCH`: Ask token ID does not match the collectible\n- `COLLECTIBLE_ONCHAIN_OWNER_MISMATCH`: On chain owner mismatch"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["COLLECTIBLE_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["ASK_ORDER_INSERT_FAILED","ASK_ORDER_UPDATE_FAILED","CREATE_SELL_OFFER_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `ASK_ORDER_INSERT_FAILED`: Failed to insert ask order\n- `ASK_ORDER_UPDATE_FAILED`: Failed to update ask order\n- `CREATE_SELL_OFFER_FAILED`: Failed to create sell offer\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"]}}}}}}},"/v1/marketplace/asks/{tokenId}":{"delete":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Cancel active ask","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"tokenId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["cancel-ask","cancel-bid"]},"orderId":{"type":"string"},"collectibleId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CANCELLED"]}},"required":["operation","orderId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","COLLECTIBLE_NOT_OWNED_BY_USER"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `COLLECTIBLE_NOT_OWNED_BY_USER`: Collectible not owned by user"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["COLLECTIBLE_NOT_FOUND","ACTIVE_ASK_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `ACTIVE_ASK_NOT_FOUND`: Active ask not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["CANCEL_LISTING_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `CANCEL_LISTING_FAILED`: Failed to cancel listing\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"]}}}}}}},"/v1/marketplace/bids/prepare":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare bid typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"amountInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId","amountInUsdt"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","WRONG_REQUEST_PARAMS"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["COLLECTIBLE_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/marketplace/bids":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit 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"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","INVALID_BID_SIGNATURE","INVALID_BID_FEE_BPS","BID_HAS_ALREADY_EXPIRED","BID_TOKEN_ID_MISMATCH","INSUFFICIENT_ALLOWANCE"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `INVALID_BID_SIGNATURE`: Bid signature is invalid\n- `INVALID_BID_FEE_BPS`: Invalid bid fee BPS\n- `BID_HAS_ALREADY_EXPIRED`: Bid has already expired\n- `BID_TOKEN_ID_MISMATCH`: Bid token ID does not match the collectible\n- `INSUFFICIENT_ALLOWANCE`: Insufficient token allowance for Permit2"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["COLLECTIBLE_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["BID_ORDER_INSERT_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `BID_ORDER_INSERT_FAILED`: Failed to insert bid order\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"]}}}}}}},"/v1/marketplace/bids/{orderId}":{"delete":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Cancel outgoing bid","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orderId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["cancel-ask","cancel-bid"]},"orderId":{"type":"string"},"collectibleId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CANCELLED"]}},"required":["operation","orderId","status"]}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","INVALID_OFFER_TYPE","INVALID_OFFER_STATUS"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `INVALID_OFFER_TYPE`: Invalid offer type\n- `INVALID_OFFER_STATUS`: Invalid offer status"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["OFFER_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `OFFER_NOT_FOUND`: Offer not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/marketplace/buy/prepare":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare buy-now typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"expectedTotalPriceInUsdt":{"type":"string","pattern":"^\\d+$"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","MATCHING_ASK_NOT_FOUND","SAFE_ACCOUNT_NOT_FOUND","WRONG_REQUEST_PARAMS"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `MATCHING_ASK_NOT_FOUND`: Matching ask not found\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["COLLECTIBLE_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"409":{"description":"Ask price changed","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/marketplace/buy":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit signed buy-now 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"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","MATCHING_ASK_NOT_FOUND","MATCHING_ASK_PERMIT_NOT_FOUND","BUY_NOW_FAILED","INVALID_ASK_SIGNATURE","ASK_HAS_ALREADY_EXPIRED","INVALID_BID_SIGNATURE","INVALID_BID_FEE_BPS","BID_HAS_ALREADY_EXPIRED","BID_TOKEN_ID_MISMATCH","INSUFFICIENT_ALLOWANCE"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `MATCHING_ASK_NOT_FOUND`: Matching ask not found\n- `MATCHING_ASK_PERMIT_NOT_FOUND`: Matching ask permit not found\n- `BUY_NOW_FAILED`: Failed to buy now\n- `INVALID_ASK_SIGNATURE`: Ask signature is invalid\n- `ASK_HAS_ALREADY_EXPIRED`: Ask has already expired\n- `INVALID_BID_SIGNATURE`: Bid signature is invalid\n- `INVALID_BID_FEE_BPS`: Invalid bid fee BPS\n- `BID_HAS_ALREADY_EXPIRED`: Bid has already expired\n- `BID_TOKEN_ID_MISMATCH`: Bid token ID does not match the collectible\n- `INSUFFICIENT_ALLOWANCE`: Insufficient token allowance for Permit2"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["COLLECTIBLE_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["MATCHING_ASK_SHOULD_BE_ONLY_ONE","EXECUTE_TRADE_INTERNAL_FAILED","BID_ORDER_INSERT_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `MATCHING_ASK_SHOULD_BE_ONLY_ONE`: Matching ask should be only one\n- `EXECUTE_TRADE_INTERNAL_FAILED`: Failed to execute trade internally\n- `BID_ORDER_INSERT_FAILED`: Failed to insert bid order\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"]}}}}}}},"/v1/marketplace/sell/prepare":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Prepare accept-bid typed data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^\\d+$"},"bidOrderId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tokenId","bidOrderId"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","SAFE_ACCOUNT_NOT_FOUND","WRONG_REQUEST_PARAMS"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `SAFE_ACCOUNT_NOT_FOUND`: Safe account not found\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"404":{"description":"Bid or card not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["COLLECTIBLE_NOT_FOUND","ORDER_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `ORDER_NOT_FOUND`: Order not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["FUNCTION_ERROR"],"description":"Possible codes:\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"]}}}}}}},"/v1/marketplace/sell":{"post":{"tags":["Marketplace v1"],"security":[{"apiKeyAuth":[],"builderAuth":[]}],"summary":"Submit signed accept-bid ask","requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"askSignature":{"type":"string"}},"required":["bidOrderId","collectibleId","askData","askSignature"]}}}},"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":{"code":{"type":"string","enum":["WRONG_REQUEST_PARAMS","INVALID_SCHEMA","INVALID_OFFER_TYPE","INVALID_OFFER_STATUS","BID_LOWER_THAN_ASK","INVALID_ASK_SIGNATURE","ASK_HAS_ALREADY_EXPIRED","ASK_TOKEN_ID_MISMATCH","COLLECTIBLE_ONCHAIN_OWNER_MISMATCH"],"description":"Possible codes:\n- `WRONG_REQUEST_PARAMS`: The request payload is invalid\n- `INVALID_SCHEMA`: Invalid schema\n- `INVALID_OFFER_TYPE`: Invalid offer type\n- `INVALID_OFFER_STATUS`: Invalid offer status\n- `BID_LOWER_THAN_ASK`: Bid amount is lower than current ask price\n- `INVALID_ASK_SIGNATURE`: Ask signature is invalid\n- `ASK_HAS_ALREADY_EXPIRED`: Ask has already expired\n- `ASK_TOKEN_ID_MISMATCH`: Ask token ID does not match the collectible\n- `COLLECTIBLE_ONCHAIN_OWNER_MISMATCH`: On chain owner mismatch"},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Possible codes:\n- `UNAUTHORIZED`: You are not authorized to perform this action"},"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":["COLLECTIBLE_NOT_FOUND","OFFER_NOT_FOUND","BUILDER_USER_NOT_ONBOARDED"],"description":"Possible codes:\n- `COLLECTIBLE_NOT_FOUND`: Collectible not found\n- `OFFER_NOT_FOUND`: Offer not found\n- `BUILDER_USER_NOT_ONBOARDED`: This wallet has no Renaiss account with a Safe yet. Sign in at renaiss.xyz with this wallet, then retry."},"message":{"type":"string"},"error":{"type":"string","description":"Debug info for local development only, never leak internals in production"}},"required":["code","message"]}}}},"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":{"code":{"type":"string","enum":["MATCHING_BID_PERMIT_NOT_FOUND","ACCEPT_OFFER_HANDLER_FAILED","EXECUTE_TRADE_INTERNAL_FAILED","ASK_ORDER_INSERT_FAILED","FUNCTION_ERROR"],"description":"Possible codes:\n- `MATCHING_BID_PERMIT_NOT_FOUND`: Matching bid permit not found\n- `ACCEPT_OFFER_HANDLER_FAILED`: Failed to process accept-offer activity\n- `EXECUTE_TRADE_INTERNAL_FAILED`: Failed to execute trade internally\n- `ASK_ORDER_INSERT_FAILED`: Failed to insert ask order\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"]}}}}}}},"/v1/cards/{tokenId}":{"get":{"tags":["Cards v1"],"summary":"Get card by token ID","description":"Returns public card data for CLI and detail views. Price details and activity history can be requested explicitly.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"tokenId","in":"path"},{"schema":{"type":"boolean"},"required":false,"name":"includeActivities","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"activitiesCursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"activitiesLimit","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"verbosePrice","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"collectible":{"type":"object","properties":{"tokenId":{"type":"string","pattern":"^d+$"},"name":{"type":"string"},"setName":{"type":"string"},"cardNumber":{"type":"string"},"pokemonName":{"type":"string"},"ownerAddress":{"type":"string","minLength":42,"maxLength":42},"askPriceInUSDT":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-ASK-PRICE"]}]},"askExpiresAt":{"type":"string"},"fmvPriceInUSD":{"anyOf":[{"type":"string","pattern":"^d+$"},{"type":"string","enum":["NO-FMV-PRICE"]}]},"fmvUpdatedAt":{"type":"string","nullable":true},"frontImageUrl":{"type":"string","format":"uri"},"backImageUrl":{"type":"string","format":"uri"},"frontWithoutStandImageUrl":{"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},"custodyProvider":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"businessName":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["id","businessName","countryCode"]},"vaultRegionCountryCode":{"type":"string"},"owner":{"type":"object","nullable":true,"properties":{"username":{"type":"string"}},"required":["username"]}},"required":["tokenId","name","setName","cardNumber","pokemonName","ownerAddress","askPriceInUSDT","fmvPriceInUSD","fmvUpdatedAt","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"]}},"offers":{"type":"array","items":{"type":"object","properties":{"from":{"type":"object","properties":{"username":{"type":"string"},"address":{"type":"string"}},"required":["username","address"]},"timestamp":{"type":"string"},"amount":{"type":"object","properties":{"value":{"type":"string"},"token":{"anyOf":[{"type":"string","enum":["USDT"]},{"type":"string","enum":["USD"]}]}},"required":["value","token"]},"status":{"type":"string","enum":["accepted","waiting","expired"]},"expiresAt":{"type":"string"}},"required":["from","timestamp","amount","status","expiresAt"]}}},"required":["top_offer","last_sale"]},"activities":{"type":"object","nullable":true,"properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"tokenAmount":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["mint"]}},"required":["user","timestamp","blockNumber","txHash","tokenAmount","tokenId","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"tokenAmount":{"type":"string","pattern":"^d+$"},"tokenId":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["burn"]}},"required":["user","timestamp","blockNumber","txHash","tokenAmount","tokenId","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"to":{"type":"string"},"tokenId":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["transfer"]}},"required":["user","timestamp","blockNumber","txHash","to","tokenId","type"]},{"type":"object","properties":{"user":{"type":"string"},"timestamp":{"type":"string","pattern":"^d+$"},"blockNumber":{"type":"string","pattern":"^d+$"},"txHash":{"type":"string"},"bidder":{"type":"string"},"asker":{"type":"string"},"nftTokenId":{"type":"string","pattern":"^d+$"},"erc20Token":{"type":"string"},"amount":{"type":"string","pattern":"^d+$"},"feeAccrued":{"type":"string","pattern":"^d+$"},"type":{"type":"string","enum":["sell"]}},"required":["user","timestamp","blockNumber","txHash","bidder","asker","nftTokenId","erc20Token","amount","feeAccrued","type"]}]}},"nextCursor":{"type":"string","nullable":true}},"required":["activities","nextCursor"]}},"required":["collectible","pricing","activities"]}}}},"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"]}}}}}}},"/v1/config/contract-addresses":{"get":{"tags":["Config v1"],"summary":"Get contract addresses","description":"Returns public contract addresses that CLI clients need for onchain reads and signing flows.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"contractAddresses":{"type":"object","properties":{"nftAddress":{"type":"string"},"usdtAddress":{"type":"string"},"permit2Address":{"type":"string"}},"required":["nftAddress","usdtAddress","permit2Address"]}},"required":["chainId","contractAddresses"]}}}},"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/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"]}}}}}}},"/api/auth/siwe/nonce":{"post":{"tags":["Auth"],"security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string","minLength":42,"maxLength":42},"address":{"type":"string","minLength":42,"maxLength":42},"chainId":{"type":"number"}}}}}},"responses":{"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/siwe/verify":{"post":{"tags":["Auth"],"security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1},"signature":{"type":"string","minLength":1},"walletAddress":{"type":"string","minLength":42,"maxLength":42},"chainId":{"type":"number"},"email":{"type":"string"}},"required":["message","signature","walletAddress"]}}}},"responses":{"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/api-key/create":{"post":{"tags":["Auth"],"description":"Creates a user-owned API key for the current Better Auth bearer session. The returned key is shown only once.","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":32},"expiresIn":{"type":"integer","minimum":86400,"maximum":31536000,"description":"Expiration time in seconds."},"prefix":{"type":"string","minLength":1,"maxLength":32}}}}}},"responses":{"200":{"description":"API key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the API key"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"name":{"type":"string","nullable":true,"description":"Name of the API key"},"prefix":{"type":"string","nullable":true,"description":"Prefix of the API key"},"start":{"type":"string","nullable":true,"description":"Starting characters of the key (if configured)"},"key":{"type":"string","description":"The full API key (only returned on creation)"},"enabled":{"type":"boolean","description":"Whether the key is enabled"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Expiration timestamp"},"referenceId":{"type":"string","description":"ID of the reference owning the key"},"lastRefillAt":{"type":"string","format":"date-time","nullable":true,"description":"Last refill timestamp"},"lastRequest":{"type":"string","format":"date-time","nullable":true,"description":"Last request timestamp"},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"description":"Metadata associated with the key"},"rateLimitMax":{"type":"number","nullable":true,"description":"Maximum requests in time window"},"rateLimitTimeWindow":{"type":"number","nullable":true,"description":"Rate limit time window in milliseconds"},"remaining":{"type":"number","nullable":true,"description":"Remaining requests"},"refillAmount":{"type":"number","nullable":true,"description":"Amount to refill"},"refillInterval":{"type":"number","nullable":true,"description":"Refill interval in milliseconds"},"rateLimitEnabled":{"type":"boolean","description":"Whether rate limiting is enabled"},"requestCount":{"type":"number","description":"Current request count in window"},"permissions":{"type":"object","nullable":true,"additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Permissions associated with the key"}},"required":["id","createdAt","updatedAt","key","enabled","referenceId","rateLimitEnabled","requestCount"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}},"summary":"Create API key"}}},"tags":[{"name":"Auth","description":"Renaiss auth endpoints for wallet sign-in and sessions."}]}