{"openapi":"3.1.0","info":{"title":"VCCPilot API","version":"1"},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]},"AccountSummaryResponse":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"companyName":{"type":"string"},"status":{"type":"string","enum":["active","suspended","closed"]},"kycTier":{"type":"integer"},"kycStatus":{"type":"string"},"onComplianceHold":{"type":"boolean"},"rank":{"type":"string","enum":["bronze","silver","gold","platinum"]},"perks":{"$ref":"#/components/schemas/AccountRankPerks"}},"required":["workspaceId","companyName","status","kycTier","kycStatus","onComplianceHold","rank","perks"]},"AccountUpdateRequest":{"type":"object","properties":{"companyName":{"type":"string","minLength":1,"maxLength":200},"contactPhone":{"type":["string","null"],"maxLength":64},"contactTelegram":{"type":["string","null"],"maxLength":64}},"additionalProperties":false},"WalletTopupRequest":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","eth","tron"],"description":"bsc or eth (BEP20/ERC20 USDT). tron returns 422 — connect a wallet in-app."},"asset":{"type":"string","enum":["usdt"],"default":"usdt"}},"required":["chain"]},"WalletTopupResponse":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","eth"]},"asset":{"type":"string","enum":["usdt"]},"depositAddress":{"type":"string"},"minDepositUsdCents":{"type":"integer"},"confirmationsRequired":{"type":"integer"},"qrSvg":{"type":"string"}},"required":["chain","asset","depositAddress","minDepositUsdCents","confirmationsRequired","qrSvg"]},"AccountRankPerks":{"type":"object","properties":{"cashbackRateBps":{"type":"integer"},"depositFxRate":{"type":"number"},"freeCardQuota":{"type":"integer"},"features":{"type":"array","items":{"type":"string"}}},"required":["cashbackRateBps","depositFxRate","freeCardQuota","features"]}},"parameters":{},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Server-to-server API key. Send it as `Authorization: Bearer cbk_live_…`."}}},"paths":{"/v1/cards":{"get":{"tags":["cards"],"summary":"Customer card list — workspace-scoped + (for members) assignment-scoped. Sort: newest first. Cursor pagination, limit ≤ 200.","parameters":[{"schema":{"type":"string","enum":["active","paused","inactive","closed","expired"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated card summary list with cursor for the next page.","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"last4":{"type":"string","pattern":"^[0-9]{4}$"},"status":{"type":"string","enum":["active","paused","inactive","closed","expired"]},"expMonth":{"type":["integer","null"],"minimum":1,"maximum":12},"expYear":{"type":["integer","null"],"minimum":2026,"maximum":2099},"assignedToUserId":{"type":["string","null"],"format":"uuid"},"network":{"type":"string","enum":["visa","mastercard"]},"spendingConstraint":{"type":["object","null"],"properties":{"period":{"type":"string","enum":["daily","weekly","monthly","yearly","lifetime"]},"limitCents":{"type":"integer","minimum":0},"minTxCents":{"type":["integer","null"],"minimum":0},"maxTxCents":{"type":["integer","null"],"minimum":0}},"required":["period","limitCents","minTxCents","maxTxCents"],"additionalProperties":false},"issuedViaManual":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"cardUsedCents":{"type":["integer","null"],"minimum":0},"cardLimitCents":{"type":["integer","null"],"minimum":0},"hasSpent":{"type":"boolean"}},"required":["id","name","last4","status","expMonth","expYear","assignedToUserId","network","spendingConstraint","issuedViaManual","createdAt","cardUsedCents","cardLimitCents","hasSpent"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}},"required":["cards","nextCursor"],"additionalProperties":false}}}},"403":{"description":"No active workspace membership (HIGH-4 gate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/cards/{id}":{"get":{"tags":["cards"],"summary":"Card detail (workspace + assignment-scoped). Returns 404 not_found for cards outside the workspace OR (for members) unassigned cards — never 403, to prevent existence-pattern leak.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Card detail.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"last4":{"type":"string","pattern":"^[0-9]{4}$"},"status":{"type":"string","enum":["active","paused","inactive","closed","expired"]},"expMonth":{"type":["integer","null"],"minimum":1,"maximum":12},"expYear":{"type":["integer","null"],"minimum":2026,"maximum":2099},"assignedToUserId":{"type":["string","null"],"format":"uuid"},"network":{"type":"string","enum":["visa","mastercard"]},"spendingConstraint":{"type":["object","null"],"properties":{"period":{"type":"string","enum":["daily","weekly","monthly","yearly","lifetime"]},"limitCents":{"type":"integer","minimum":0},"minTxCents":{"type":["integer","null"],"minimum":0},"maxTxCents":{"type":["integer","null"],"minimum":0}},"required":["period","limitCents","minTxCents","maxTxCents"],"additionalProperties":false},"issuedViaManual":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"cardUsedCents":{"type":["integer","null"],"minimum":0},"cardLimitCents":{"type":["integer","null"],"minimum":0},"hasSpent":{"type":"boolean"},"groupLimitCents":{"type":["integer","null"],"minimum":0},"groupUsedCents":{"type":["integer","null"],"minimum":0},"cardNextResetAt":{"type":["string","null"],"format":"date-time"}},"required":["id","name","last4","status","expMonth","expYear","assignedToUserId","network","spendingConstraint","issuedViaManual","createdAt","cardUsedCents","cardLimitCents","hasSpent","groupLimitCents","groupUsedCents","cardNextResetAt"],"additionalProperties":false}}}},"403":{"description":"No active workspace membership.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Card not found OR not accessible to this caller (existence-pattern defense — see handler comment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/transactions":{"get":{"tags":["transactions"],"summary":"Customer transactions list — workspace-scoped + (for members) assigned-card-scoped. Newest first. Classic offset pagination (page + pageSize 25/50/100).","parameters":[{"schema":{"type":["string","null"]},"required":false,"name":"from","in":"query"},{"schema":{"type":["string","null"]},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["pending","settled","declined","refunded","reversed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"cardId","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,4}$"},"required":false,"name":"cardLast4","in":"query"},{"schema":{"type":"string","pattern":"^\\d{3,4}$"},"required":false,"name":"mcc","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"country","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"amountMin","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"amountMax","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"name":"merchant","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","default":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","enum":["when","amount","merchant"],"default":"when"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"dir","in":"query"}],"responses":{"200":{"description":"One page of transactions + the total count for \"Page X of Y\".","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"occurredAt":{"type":"string","format":"date-time"},"amountCents":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","settled","declined","refunded","reversed"]},"detailedStatus":{"type":"string"},"merchantName":{"type":["string","null"]},"merchantDescriptor":{"type":["string","null"]},"merchantCategoryCode":{"type":["string","null"]},"merchantCountry":{"type":["string","null"]},"cashbackEligible":{"type":"boolean"},"cardId":{"type":["string","null"],"format":"uuid"},"cardName":{"type":["string","null"]},"cardLast4":{"type":["string","null"]},"declineReason":{"type":["string","null"]}},"required":["id","occurredAt","amountCents","currency","status","detailedStatus","merchantName","merchantDescriptor","merchantCategoryCode","merchantCountry","cashbackEligible","cardId","cardName","cardLast4","declineReason"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1}},"required":["items","total","page","pageSize"],"additionalProperties":false}}}}},"security":[{"bearerAuth":[]}]}},"/v1/transactions/{id}":{"get":{"tags":["transactions"],"summary":"Customer transaction detail. Returns 404 for tx outside workspace OR (members) unassigned cards.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Transaction detail.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"occurredAt":{"type":"string","format":"date-time"},"amountCents":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","settled","declined","refunded","reversed"]},"detailedStatus":{"type":"string"},"merchantName":{"type":["string","null"]},"merchantDescriptor":{"type":["string","null"]},"merchantCategoryCode":{"type":["string","null"]},"merchantCountry":{"type":["string","null"]},"cashbackEligible":{"type":"boolean"},"cardId":{"type":["string","null"],"format":"uuid"},"cardName":{"type":["string","null"]},"cardLast4":{"type":["string","null"]},"declineReason":{"type":["string","null"]},"merchantCity":{"type":["string","null"]},"merchantState":{"type":["string","null"]},"ingestedAt":{"type":"string","format":"date-time"},"cashbackRate":{"type":["string","null"]},"cashbackAmountCents":{"type":["string","null"]},"refundedFor":{"type":["string","null"],"format":"uuid"},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"occurredAt":{"type":"string","format":"date-time"},"amountCents":{"type":"string"},"status":{"type":"string","enum":["pending","settled","declined","refunded","reversed"]}},"required":["id","occurredAt","amountCents","status"]}}},"required":["id","occurredAt","amountCents","currency","status","detailedStatus","merchantName","merchantDescriptor","merchantCategoryCode","merchantCountry","cashbackEligible","cardId","cardName","cardLast4","declineReason","merchantCity","merchantState","ingestedAt","cashbackRate","cashbackAmountCents","refundedFor","refunds"]}}}},"404":{"description":"Not found OR outside the caller's visibility.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/cashback/summary":{"get":{"tags":["cashback"],"summary":"Cashback hero summary — range-earned, eligible spend, current tier rate, next payout, rank-explainer. Fast path (~50ms) for the page hero. Per plan/implementation/07-cashback.md PR-A.","parameters":[{"schema":{"type":"string","enum":["30d","90d","ytd"],"default":"90d"},"required":false,"name":"range","in":"query"}],"responses":{"200":{"description":"Hero summary for the chosen range.","content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string","enum":["30d","90d","ytd"],"default":"90d"},"rangeLabel":{"type":"string"},"earnedAmountCents":{"type":"integer"},"eligibleSpendCents":{"type":"integer"},"estimatedThisMonthCents":{"type":"integer"},"estimateFinalizesOnLabel":{"type":"string"},"estimateEligibleSpendCents":{"type":"integer"},"currentRateBps":{"type":"integer"},"cashbackTier":{"type":"string","enum":["none","bronze","silver","gold","platinum"]},"accountRank":{"type":"string","enum":["none","bronze","silver","gold","platinum"]},"capCents":{"type":["integer","null"]},"eligibilityLabel":{"type":"string"},"nextPayout":{"type":["object","null"],"properties":{"scheduledForIso":{"type":"string","format":"date-time"},"scheduledForLabel":{"type":"string"},"expectedAmountCents":{"type":"integer"},"daysAway":{"type":"integer","minimum":0},"periodMonthLabel":{"type":"string"}},"required":["scheduledForIso","scheduledForLabel","expectedAmountCents","daysAway","periodMonthLabel"]},"lastMonth":{"type":"object","properties":{"label":{"type":"string"},"earnedCents":{"type":"integer","minimum":0},"eligibleSpendCents":{"type":"integer","minimum":0},"rateBps":{"type":"integer","minimum":0},"finalized":{"type":"boolean"},"payout":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["pending","paid"]},"dateLabel":{"type":"string"},"daysAway":{"type":"integer","minimum":0}},"required":["status","dateLabel","daysAway"]}},"required":["label","earnedCents","eligibleSpendCents","rateBps","finalized","payout"]},"rankExplainer":{"type":["object","null"],"properties":{"accountRank":{"type":"string","enum":["none","bronze","silver","gold","platinum"]},"cashbackTier":{"type":"string","enum":["none","bronze","silver","gold","platinum"]}},"required":["accountRank","cashbackTier"]},"attribution":{"type":["object","null"],"properties":{"memberCardCount":{"type":"integer","minimum":0},"memberEligibleSpendCents":{"type":"integer","minimum":0},"workspaceEligibleSpendCents":{"type":"integer","minimum":0},"sharePercent":{"type":["number","null"],"minimum":0,"maximum":100}},"required":["memberCardCount","memberEligibleSpendCents","workspaceEligibleSpendCents","sharePercent"]}},"required":["rangeLabel","earnedAmountCents","eligibleSpendCents","estimatedThisMonthCents","estimateFinalizesOnLabel","estimateEligibleSpendCents","currentRateBps","cashbackTier","accountRank","capCents","eligibilityLabel","nextPayout","lastMonth","rankExplainer","attribution"]}}}},"403":{"description":"Role lacks `cashback.view`. Post-2026-05-23 (08-team narrowing PR-A2): both owner and member grant this; the 403 path fires for an admin-class user with no active workspace membership.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Workspace ambiguous (multi-membership user without X-Workspace-ID header).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/wallet":{"get":{"tags":["wallet"],"summary":"Customer wallet header — USD balance + holds + per-rank FX rate + lifetime-deposit summary. Backed by `balance_state` (R3-03 — never re-summed from `wallet_ledger`).","responses":{"200":{"description":"The wallet overview for the requester’s active workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"walletId":{"type":"string"},"balanceCents":{"type":"integer","minimum":0},"holdCents":{"type":"integer","minimum":0},"spentCents":{"type":"integer","minimum":0},"availableCents":{"type":"integer","minimum":0},"accountRank":{"type":"string","enum":["bronze","silver","gold","platinum"]},"fxRate":{"type":"number","exclusiveMinimum":0},"peerFxRates":{"type":"object","properties":{"bronze":{"type":"number","exclusiveMinimum":0},"silver":{"type":"number","exclusiveMinimum":0},"gold":{"type":"number","exclusiveMinimum":0},"platinum":{"type":"number","exclusiveMinimum":0}},"required":["bronze","silver","gold","platinum"]},"confirmations":{"type":"object","properties":{"tron":{"type":"integer","exclusiveMinimum":0},"bsc":{"type":"integer","exclusiveMinimum":0},"eth":{"type":"integer","exclusiveMinimum":0}},"required":["tron","bsc"]},"minDepositCents":{"type":"integer","minimum":0},"openingFee":{"type":["object","null"],"properties":{"feeCents":{"type":"integer","exclusiveMinimum":0}},"required":["feeCents"]},"ledgerSummary":{"type":"object","properties":{"lifetimeDepositedCents":{"type":"integer","minimum":0},"lifetimeCashbackCents":{"type":"integer","minimum":0},"depositCount":{"type":"integer","minimum":0},"networkCount":{"type":"integer","minimum":0}},"required":["lifetimeDepositedCents","lifetimeCashbackCents","depositCount","networkCount"]}},"required":["walletId","balanceCents","holdCents","spentCents","availableCents","accountRank","fxRate","peerFxRates","confirmations","minDepositCents","ledgerSummary"]}}}},"403":{"description":"The caller has no active workspace membership (HIGH-4 gate — admin-class users never see the customer wallet shape).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/wallet/my-deposits":{"get":{"tags":["wallet"],"summary":"Offset-paginated listing of the workspace's deposit history (`page`/`pageSize` + `total`). Maps the 10-state internal `deposits.status` to the 4-bucket customer view (`pending`/`processing`/`credited`/`review`).","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","default":25},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"A page of deposits + the full filtered `total` (drives \"Page X of Y\") + the page-spanning `feeEvents` and `topupEvents` sidecars.","content":{"application/json":{"schema":{"type":"object","properties":{"deposits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"chain":{"type":"string","enum":["tron","bsc","eth"]},"asset":{"type":"string","enum":["usdt","usdc"],"default":"usdt"},"txHash":{"type":"string"},"amountUsdtCents":{"type":"integer","minimum":0},"amountCreditedCents":{"type":"integer","minimum":0},"appliedFxRate":{"type":["number","null"],"exclusiveMinimum":0},"status":{"type":"string","enum":["pending","processing","credited","review","not_credited"]},"detectedAt":{"type":"string","format":"date-time"},"confirmedAt":{"type":["string","null"],"format":"date-time"},"creditedAt":{"type":["string","null"],"format":"date-time"},"confirmationCount":{"type":["integer","null"],"minimum":0},"requiredConfirmations":{"type":"integer","exclusiveMinimum":0}},"required":["id","chain","txHash","amountUsdtCents","amountCreditedCents","appliedFxRate","status","detectedAt","confirmedAt"]}},"total":{"type":"integer","minimum":0},"feeEvents":{"type":"array","items":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMaximum":0},"description":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"refDepositId":{"type":["string","null"],"format":"uuid"}},"required":["amountCents","description","occurredAt","refDepositId"]}},"topupEvents":{"type":"array","items":{"type":"object","properties":{"amountCreditedCents":{"type":"integer","exclusiveMinimum":0},"network":{"type":"string","enum":["tron","bsc","eth"]},"asset":{"type":"string","enum":["usdt","usdc"]},"occurredAt":{"type":"string","format":"date-time"}},"required":["amountCreditedCents","network","asset","occurredAt"]}}},"required":["deposits"]}}}},"403":{"description":"The caller has no active workspace membership (HIGH-4 gate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/card-requests":{"get":{"tags":["cards"],"summary":"Customer's card-request list — workspace-scoped + (for members) own-submitted only. Sort: newest first. Cursor pagination, limit ≤ 200.","parameters":[{"schema":{"type":"string","enum":["pending","issuing","issued","partial","rejected","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated card-request summary list with cursor for the next page.","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":100},"network":{"type":"string","enum":["visa","mastercard"]},"feeCents":{"type":"integer","minimum":0},"status":{"type":"string","enum":["pending","issuing","issued","partial","rejected","cancelled"]},"customerMessage":{"type":["string","null"],"maxLength":2000},"outcomes":{"type":"object","properties":{"issued":{"type":"integer","minimum":0},"failedPermanent":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}},"required":["issued","failedPermanent","pending"],"additionalProperties":false},"issuedCardIds":{"type":"array","items":{"type":"string","format":"uuid"}},"submittedAt":{"type":"string","format":"date-time"},"claimedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","quantity","network","feeCents","status","customerMessage","outcomes","issuedCardIds","submittedAt","claimedAt","completedAt"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}},"required":["requests","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Ambiguous workspace (≥2 active memberships, no X-Workspace-Id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active workspace membership.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["cards"],"summary":"Submit a card-issuance request. Workspace must have card_issuance_enabled=true; compliance hold blocks; rate-limited 10/workspace/hour.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":100},"network":{"type":"string","enum":["visa","mastercard"]},"acknowledgedFeeCents":{"type":"integer","minimum":0,"default":0}},"required":["quantity","network"],"additionalProperties":false}}}},"responses":{"201":{"description":"Card request submitted; ops fulfills via the admin queue.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"submittedAt":{"type":"string","format":"date-time"},"eta":{"type":"string","minLength":1,"maxLength":100}},"required":["requestId","submittedAt","eta"],"additionalProperties":false}}}},"400":{"description":"Body validation failed OR ambiguous workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active workspace membership (403 not_a_member) OR workspace card issuance disabled (403 card_issuance_locked) OR available balance at/below the issuance floor (403 needs_deposit) OR member lacks card_request.submit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"card_request_already_open — the workspace already has a card request still being processed (pending/issuing). Let it finish or be rejected/cancelled before submitting another.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"Workspace is on compliance hold.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (10 requests per workspace per UTC hour).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/account":{"get":{"tags":["account"],"summary":"Read your account summary — company name, account status, verification tier/status, compliance-hold flag, and rank perks. Excludes login email, team roster, and verification documents.","responses":{"200":{"description":"The account summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSummaryResponse"}}}},"403":{"description":"No active workspace membership, or the caller lacks `account.read`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"put":{"tags":["account"],"summary":"Update your company profile — companyName (also your display name) and contact channels. Send null to clear a contact field. At least one field is required.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUpdateRequest"}}}},"responses":{"200":{"description":"Updated; echoes the full account summary with the new values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSummaryResponse"}}}},"400":{"description":"Body validation failed, or no editable field was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active workspace membership, demo workspace (read-only), or the caller lacks `account.profile.edit`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The workspace is not in `active` status (suspended/closed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/wallet/topups":{"post":{"tags":["wallet"],"summary":"Get the BSC/ETH (BEP20/ERC20) USDT deposit address to fund this workspace (idempotent). TRON requires connecting a wallet in-app.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTopupRequest"}}}},"responses":{"200":{"description":"The EVM deposit address + funding parameters. Send USDT here; the balance credits after on-chain confirmation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTopupResponse"}}}},"403":{"description":"No active membership, demo workspace, or crypto deposits disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The requested chain is not currently enabled for deposits (e.g. ETH dark by default).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"TRON is not supported via the API — connect a wallet in-app.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}}},"webhooks":{}}