{"openapi":"3.0.3","info":{"title":"tZERO Institutional API Documents","description":"## Overview\n\nThe **tZERO Institutional API** — programmatic access to transfer-agent, tokenization, and custody operations for institutional issuers and partners. Production base URL `api.t0direct.com`.\n\n### Authentication\nAll requests require an API key in the `X-API-Key` header. Generate keys at [app.t0kenizer.com/ta/api-keys](https://app.t0kenizer.com/ta/api-keys).\n\n```\nX-API-Key: t0k_your_api_key_here\n```\n\n### Scopes\nKeys are issued with one or more scopes. A request to an endpoint whose\nrequired scope the key lacks returns `403 FORBIDDEN`. `FULL_ACCESS` satisfies\nevery scope.\n\n**Transfer Agent**\n- `TA_READ` — Read investors, securities, holdings, documents, dividends, corporate actions, proposals\n- `TA_WRITE` — Create/update investors, submit issuances, declare dividends and corporate actions, create voting proposals\n- `TA_TRANSFERS` — Submit and manage book-entry transfers\n- `TA_ADMIN` — Administrative TA operations\n\n**Tokenization** (read-only today)\n- `TOKENS_READ` — Read token configurations and deployments\n- `DEPLOYMENTS_READ` — Read deployments and operation history\n\n> The investor registry / cap table is served by the Transfer Agent **Investors** endpoints (`TA_READ` / `TA_WRITE`).\n\n**Custody** (read-only today)\n- `CUSTODY_READ` — Read vaults, balances, transfers, and whitelisted addresses\n\n> Write scopes (`TOKENS_WRITE`, `DEPLOYMENTS_WRITE`, `PRICE_WRITE`, `CUSTODY_WRITE`, `CAPTABLE_*`) exist in the enum but are **reserved** — exposed only when those capabilities are opened to customers.\n\n**Master**\n- `FULL_ACCESS` — Satisfies all scopes (use sparingly)\n\n### Base URL\n```\nhttps://api.t0direct.com/api/v1\n```\n\n### Pagination\nList endpoints support `page` and `perPage` query parameters. Responses include a `pagination` object with `total`, `page`, `perPage`, and `totalPages`.\n\n### Idempotency\nTransfer and issuance requests support an `idempotencyKey` field. Submitting the same key twice returns the original record without creating a duplicate.\n\nDividend, corporate-action, and proposal mutations require an `Idempotency-Key` **header**. An exact retry replays the original response; reusing a key with a different payload returns `409 Conflict`.\n\n### Corporate actions, dividends & voting (review-gated)\nDeclarations submitted through `/v1/dividends`, `/v1/corporate-actions`, and `/v1/proposals` enter `PENDING_REVIEW` — a tZERO transfer-agent reviewer approves or rejects each one under a regulatory turnaround timer (SEC Rule 17Ad-2). Approved actions execute according to the security's execution target; on-chain executions (dividend creation on the claim contract, split initialization, vote anchoring) settle via tZERO's Fireblocks custody and surface transaction hashes on the entity.\n\nVoting proposals support per-token `votingMode`: `OFF_CHAIN` (transfer-agent register) or `ON_CHAIN` (record-block eligibility from token checkpoints, privacy-preserving ballot commitments, and Merkle-root anchors published on the token's chain). Investors vote in their own t0kenizer portal accounts — ballots cannot be submitted through this API. Track lifecycle via `ta.dividend.*`, `ta.corporate_action.*`, and `ta.proposal.*` webhook events.\n\n### Webhooks\nSubscribe to events at `POST /v1/webhooks`. Payloads are signed with HMAC-SHA256 using your webhook secret.","version":"1.1.0","contact":{"name":"T0kenizer API Support","email":"api@t0direct.com"}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key generated at app.t0kenizer.com/ta/api-keys"}},"schemas":{"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching records"},"page":{"type":"integer","description":"Current page number"},"perPage":{"type":"integer","description":"Records per page"},"totalPages":{"type":"integer","description":"Total number of pages"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"T0K-V1-INV-001"},"message":{"type":"string","example":"Investor not found"}}}}},"TokenConfig":{"type":"object","description":"A token configuration (the blueprint). Deployments are its on-chain instances.","properties":{"id":{"type":"string","description":"CUID"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer","example":18},"initialSupply":{"type":"string","description":"Integer as string"},"supplyCap":{"type":"string","nullable":true,"description":"Integer as string"},"price":{"type":"number","nullable":true},"assetType":{"type":"string","nullable":true},"assetClass":{"type":"string","nullable":true,"description":"e.g. \"t-bill\", \"mmf\", \"private-credit\""},"tokenStandard":{"type":"string","nullable":true},"mintable":{"type":"boolean"},"burnable":{"type":"boolean"},"pausable":{"type":"boolean"},"upgradeable":{"type":"boolean"},"whitelistEnabled":{"type":"boolean"},"blacklistEnabled":{"type":"boolean"},"snapshotEnabled":{"type":"boolean"},"imported":{"type":"boolean"},"delisted":{"type":"boolean"},"lifecycleStatus":{"type":"string","example":"DRAFT"},"createdAt":{"type":"string","format":"date-time"},"deployments":{"type":"array","items":{"$ref":"#/components/schemas/def-3"}}}},"Deployment":{"type":"object","description":"An on-chain instance of a token configuration on a specific chain/network.","properties":{"id":{"type":"string"},"tokenConfigId":{"type":"string"},"chain":{"type":"string","description":"Target chain (e.g. ETHEREUM, POLYGON, BESU)"},"network":{"type":"string","description":"MAINNET / TESTNET / DEVNET"},"contractAddress":{"type":"string","nullable":true},"txHash":{"type":"string","nullable":true},"status":{"type":"string","example":"DEPLOYED"},"walletAddress":{"type":"string","nullable":true},"deployedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Operation":{"type":"object","description":"A logged on-chain operation against a deployment (MINT, BURN, TRANSFER, …).","properties":{"id":{"type":"string"},"operation":{"type":"string","example":"MINT"},"params":{"type":"object","nullable":true,"additionalProperties":true},"txHash":{"type":"string","nullable":true},"txStatus":{"type":"string","example":"CONFIRMED"},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"CustodyWallet":{"type":"object","description":"An asset wallet inside a custody vault.","properties":{"id":{"type":"string"},"assetId":{"type":"string","description":"Fireblocks asset id (e.g. ETH_TEST5, USDC)"},"address":{"type":"string","nullable":true},"tag":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"CustodyVault":{"type":"object","description":"A Fireblocks-backed custody vault owned by the issuer.","properties":{"id":{"type":"string"},"name":{"type":"string"},"fireblocksVaultId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"wallets":{"type":"array","items":{"$ref":"#/components/schemas/def-5"}},"_count":{"type":"object","properties":{"wallets":{"type":"integer"},"transfers":{"type":"integer"}}}}},"CustodyTransfer":{"type":"object","description":"A transfer of assets out of a custody vault.","properties":{"id":{"type":"string"},"vaultId":{"type":"string"},"assetId":{"type":"string"},"amount":{"type":"string","description":"Decimal as string"},"destAddress":{"type":"string"},"status":{"type":"string","example":"PENDING"},"destinationType":{"type":"string","example":"ONE_TIME_ADDRESS"},"whitelistedAddressId":{"type":"string","nullable":true},"fireblocksTxId":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"WhitelistedAddressAsset":{"type":"object","properties":{"id":{"type":"string"},"assetId":{"type":"string"},"address":{"type":"string"},"tag":{"type":"string","nullable":true}}},"WhitelistedAddress":{"type":"object","description":"An external address approved to receive transfers from custody.","properties":{"id":{"type":"string"},"type":{"type":"string","description":"EXTERNAL / INTERNAL / CONTRACT"},"name":{"type":"string"},"status":{"type":"string","example":"ACTIVE"},"fireblocksWalletId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/def-8"}}}},"Investor":{"type":"object","properties":{"id":{"type":"string","description":"CUID"},"name":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"entityType":{"type":"string","enum":["INDIVIDUAL","CORPORATION","LLC","PARTNERSHIP","TRUST","FUND","DAO","OTHER"]},"jurisdiction":{"type":"string","nullable":true},"taxId":{"type":"string","nullable":true},"walletAddress":{"type":"string","nullable":true},"sharesOwned":{"type":"string","description":"Integer as string"},"ownershipPct":{"type":"string","nullable":true},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","APPROVED","REJECTED","EXPIRED"]},"kycVerifiedAt":{"type":"string","format":"date-time","nullable":true},"kycExpiresAt":{"type":"string","format":"date-time","nullable":true},"kybStatus":{"type":"string","nullable":true},"accreditationStatus":{"type":"string","enum":["NONE","PENDING","VERIFIED","EXPIRED"]},"accreditationVerifiedAt":{"type":"string","format":"date-time","nullable":true},"accreditationExpiresAt":{"type":"string","format":"date-time","nullable":true},"hasPortalAccount":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"InvestorHolding":{"type":"object","properties":{"securityId":{"type":"string","nullable":true},"securityName":{"type":"string","nullable":true},"securityType":{"type":"string","nullable":true,"description":"Security type (e.g. COMMON_STOCK)"},"symbol":{"type":"string","nullable":true,"description":"Security ticker symbol"},"shares":{"type":"string","description":"Integer as string"},"percentage":{"type":"string","nullable":true,"description":"Percentage of shares outstanding"},"lastSyncAt":{"type":"string","format":"date-time","nullable":true,"description":"Last chain-sync timestamp"}}},"Security":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string","nullable":true},"type":{"type":"string"},"status":{"type":"string"},"description":{"type":"string","nullable":true},"totalShares":{"type":"string","nullable":true,"description":"Total authorized shares (integer as string)"},"sharesOutstanding":{"type":"string","nullable":true},"parValue":{"type":"string","nullable":true},"cusip":{"type":"string","nullable":true},"isin":{"type":"string","nullable":true},"regType":{"type":"string","nullable":true,"description":"Regulatory exemption type (e.g. REG_D_506C)"},"contractAddress":{"type":"string","nullable":true,"description":"On-chain token contract address"},"chain":{"type":"string","nullable":true,"description":"Chain the token contract lives on"},"dividendRate":{"type":"number","nullable":true,"description":"Annual dividend rate %"},"liquidationPref":{"type":"number","nullable":true,"description":"Liquidation preference multiplier"},"holders":{"type":"array","items":{"$ref":"#/components/schemas/def-13"},"description":"Top 10 holders — present on the detail endpoint only"},"createdAt":{"type":"string","format":"date-time"}}},"SecurityHolder":{"type":"object","properties":{"rank":{"type":"integer"},"walletAddress":{"type":"string","nullable":true,"description":"On-chain holder wallet address"},"investorId":{"type":"string","nullable":true},"investorName":{"type":"string","nullable":true},"shares":{"type":"string","description":"Shares held (integer as string)"},"percentage":{"type":"string","nullable":true,"description":"Percentage of shares outstanding"},"lastSyncAt":{"type":"string","format":"date-time","nullable":true,"description":"Last chain-sync timestamp"}}},"TransferRequest":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"payload":{"type":"object","description":"The transfer details captured at submission time.","properties":{"fromInvestorId":{"type":"string"},"toInvestorId":{"type":"string"},"securityId":{"type":"string"},"quantity":{"type":"string","description":"Number of shares as numeric string"},"price":{"type":"string","nullable":true,"description":"Price per unit as numeric string"},"signature":{"type":"object","nullable":true,"properties":{"status":{"type":"string"},"signature":{"type":"string"},"date":{"type":"string"}}},"idempotencyKey":{"type":"string","nullable":true},"batchIdempotencyId":{"type":"string","nullable":true,"description":"Outer batch idempotency id (batch submissions only)"},"matchedOn":{"type":"string","format":"date-time","nullable":true},"settledOn":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true},"requestedBy":{"type":"string"},"reviewedBy":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"IssuanceRequest":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"payload":{"type":"object","description":"The issuance request details captured at submission time.","properties":{"investorId":{"type":"string"},"securityId":{"type":"string"},"quantity":{"type":"string","description":"Number of shares as numeric string"},"issuanceDate":{"type":"string","description":"Issuance date (ISO date or date-time)"},"recipientType":{"type":"string","description":"Why the issuance was submitted (e.g. PRIMARY_OFFERING)"},"costBasis":{"type":"string","nullable":true,"description":"Cost basis as numeric string"},"notes":{"type":"string","nullable":true},"idempotencyKey":{"type":"string","nullable":true}},"additionalProperties":true},"securityId":{"type":"string"},"investorId":{"type":"string"},"shares":{"type":"string"},"pricePerShare":{"type":"string","nullable":true},"consideration":{"type":"string","nullable":true},"memo":{"type":"string","nullable":true},"idempotencyKey":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"requestedBy":{"type":"string"},"reviewedBy":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"webhookId":{"type":"string","nullable":true,"description":"Correlation id echoed on submission responses — matches the issuanceId in ta.issuance.* webhook events"}}},"Document":{"type":"object","properties":{"id":{"type":"string"},"investorId":{"type":"string"},"investorName":{"type":"string","nullable":true,"description":"Name of the owning investor"},"documentType":{"type":"string"},"fileName":{"type":"string","nullable":true,"description":"Sanitized original filename"},"fileSize":{"type":"integer","nullable":true,"description":"File size in bytes"},"status":{"type":"string","nullable":true,"description":"Upload status (lowercased): pending / confirmed / rejected"},"uploadedBy":{"type":"string","nullable":true,"description":"Identity that initiated the upload"},"label":{"type":"string","nullable":true},"storageUrl":{"type":"string","nullable":true},"mimeType":{"type":"string","nullable":true},"sizeBytes":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"def-0":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching records"},"page":{"type":"integer","description":"Current page number"},"perPage":{"type":"integer","description":"Records per page"},"totalPages":{"type":"integer","description":"Total number of pages"}},"title":"PaginationMeta"},"def-1":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"T0K-V1-INV-001"},"message":{"type":"string","example":"Investor not found"}}}},"title":"ErrorResponse"},"def-2":{"type":"object","description":"A token configuration (the blueprint). Deployments are its on-chain instances.","properties":{"id":{"type":"string","description":"CUID"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer","example":18},"initialSupply":{"type":"string","description":"Integer as string"},"supplyCap":{"type":"string","nullable":true,"description":"Integer as string"},"price":{"type":"number","nullable":true},"assetType":{"type":"string","nullable":true},"assetClass":{"type":"string","nullable":true,"description":"e.g. \"t-bill\", \"mmf\", \"private-credit\""},"tokenStandard":{"type":"string","nullable":true},"mintable":{"type":"boolean"},"burnable":{"type":"boolean"},"pausable":{"type":"boolean"},"upgradeable":{"type":"boolean"},"whitelistEnabled":{"type":"boolean"},"blacklistEnabled":{"type":"boolean"},"snapshotEnabled":{"type":"boolean"},"imported":{"type":"boolean"},"delisted":{"type":"boolean"},"lifecycleStatus":{"type":"string","example":"DRAFT"},"createdAt":{"type":"string","format":"date-time"},"deployments":{"type":"array","items":{"$ref":"#/components/schemas/def-3"}}},"title":"TokenConfig"},"def-3":{"type":"object","description":"An on-chain instance of a token configuration on a specific chain/network.","properties":{"id":{"type":"string"},"tokenConfigId":{"type":"string"},"chain":{"type":"string","description":"Target chain (e.g. ETHEREUM, POLYGON, BESU)"},"network":{"type":"string","description":"MAINNET / TESTNET / DEVNET"},"contractAddress":{"type":"string","nullable":true},"txHash":{"type":"string","nullable":true},"status":{"type":"string","example":"DEPLOYED"},"walletAddress":{"type":"string","nullable":true},"deployedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"title":"Deployment"},"def-4":{"type":"object","description":"A logged on-chain operation against a deployment (MINT, BURN, TRANSFER, …).","properties":{"id":{"type":"string"},"operation":{"type":"string","example":"MINT"},"params":{"type":"object","nullable":true,"additionalProperties":true},"txHash":{"type":"string","nullable":true},"txStatus":{"type":"string","example":"CONFIRMED"},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"title":"Operation"},"def-5":{"type":"object","description":"An asset wallet inside a custody vault.","properties":{"id":{"type":"string"},"assetId":{"type":"string","description":"Fireblocks asset id (e.g. ETH_TEST5, USDC)"},"address":{"type":"string","nullable":true},"tag":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"title":"CustodyWallet"},"def-6":{"type":"object","description":"A Fireblocks-backed custody vault owned by the issuer.","properties":{"id":{"type":"string"},"name":{"type":"string"},"fireblocksVaultId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"wallets":{"type":"array","items":{"$ref":"#/components/schemas/def-5"}},"_count":{"type":"object","properties":{"wallets":{"type":"integer"},"transfers":{"type":"integer"}}}},"title":"CustodyVault"},"def-7":{"type":"object","description":"A transfer of assets out of a custody vault.","properties":{"id":{"type":"string"},"vaultId":{"type":"string"},"assetId":{"type":"string"},"amount":{"type":"string","description":"Decimal as string"},"destAddress":{"type":"string"},"status":{"type":"string","example":"PENDING"},"destinationType":{"type":"string","example":"ONE_TIME_ADDRESS"},"whitelistedAddressId":{"type":"string","nullable":true},"fireblocksTxId":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"title":"CustodyTransfer"},"def-8":{"type":"object","properties":{"id":{"type":"string"},"assetId":{"type":"string"},"address":{"type":"string"},"tag":{"type":"string","nullable":true}},"title":"WhitelistedAddressAsset"},"def-9":{"type":"object","description":"An external address approved to receive transfers from custody.","properties":{"id":{"type":"string"},"type":{"type":"string","description":"EXTERNAL / INTERNAL / CONTRACT"},"name":{"type":"string"},"status":{"type":"string","example":"ACTIVE"},"fireblocksWalletId":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/def-8"}}},"title":"WhitelistedAddress"},"def-10":{"type":"object","properties":{"id":{"type":"string","description":"CUID"},"name":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"entityType":{"type":"string","enum":["INDIVIDUAL","CORPORATION","LLC","PARTNERSHIP","TRUST","FUND","DAO","OTHER"]},"jurisdiction":{"type":"string","nullable":true},"taxId":{"type":"string","nullable":true},"walletAddress":{"type":"string","nullable":true},"sharesOwned":{"type":"string","description":"Integer as string"},"ownershipPct":{"type":"string","nullable":true},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","APPROVED","REJECTED","EXPIRED"]},"kycVerifiedAt":{"type":"string","format":"date-time","nullable":true},"kycExpiresAt":{"type":"string","format":"date-time","nullable":true},"kybStatus":{"type":"string","nullable":true},"accreditationStatus":{"type":"string","enum":["NONE","PENDING","VERIFIED","EXPIRED"]},"accreditationVerifiedAt":{"type":"string","format":"date-time","nullable":true},"accreditationExpiresAt":{"type":"string","format":"date-time","nullable":true},"hasPortalAccount":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"title":"Investor"},"def-11":{"type":"object","properties":{"securityId":{"type":"string","nullable":true},"securityName":{"type":"string","nullable":true},"securityType":{"type":"string","nullable":true,"description":"Security type (e.g. COMMON_STOCK)"},"symbol":{"type":"string","nullable":true,"description":"Security ticker symbol"},"shares":{"type":"string","description":"Integer as string"},"percentage":{"type":"string","nullable":true,"description":"Percentage of shares outstanding"},"lastSyncAt":{"type":"string","format":"date-time","nullable":true,"description":"Last chain-sync timestamp"}},"title":"InvestorHolding"},"def-12":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string","nullable":true},"type":{"type":"string"},"status":{"type":"string"},"description":{"type":"string","nullable":true},"totalShares":{"type":"string","nullable":true,"description":"Total authorized shares (integer as string)"},"sharesOutstanding":{"type":"string","nullable":true},"parValue":{"type":"string","nullable":true},"cusip":{"type":"string","nullable":true},"isin":{"type":"string","nullable":true},"regType":{"type":"string","nullable":true,"description":"Regulatory exemption type (e.g. REG_D_506C)"},"contractAddress":{"type":"string","nullable":true,"description":"On-chain token contract address"},"chain":{"type":"string","nullable":true,"description":"Chain the token contract lives on"},"dividendRate":{"type":"number","nullable":true,"description":"Annual dividend rate %"},"liquidationPref":{"type":"number","nullable":true,"description":"Liquidation preference multiplier"},"holders":{"type":"array","items":{"$ref":"#/components/schemas/def-13"},"description":"Top 10 holders — present on the detail endpoint only"},"createdAt":{"type":"string","format":"date-time"}},"title":"Security"},"def-13":{"type":"object","properties":{"rank":{"type":"integer"},"walletAddress":{"type":"string","nullable":true,"description":"On-chain holder wallet address"},"investorId":{"type":"string","nullable":true},"investorName":{"type":"string","nullable":true},"shares":{"type":"string","description":"Shares held (integer as string)"},"percentage":{"type":"string","nullable":true,"description":"Percentage of shares outstanding"},"lastSyncAt":{"type":"string","format":"date-time","nullable":true,"description":"Last chain-sync timestamp"}},"title":"SecurityHolder"},"def-14":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"payload":{"type":"object","description":"The transfer details captured at submission time.","properties":{"fromInvestorId":{"type":"string"},"toInvestorId":{"type":"string"},"securityId":{"type":"string"},"quantity":{"type":"string","description":"Number of shares as numeric string"},"price":{"type":"string","nullable":true,"description":"Price per unit as numeric string"},"signature":{"type":"object","nullable":true,"properties":{"status":{"type":"string"},"signature":{"type":"string"},"date":{"type":"string"}}},"idempotencyKey":{"type":"string","nullable":true},"batchIdempotencyId":{"type":"string","nullable":true,"description":"Outer batch idempotency id (batch submissions only)"},"matchedOn":{"type":"string","format":"date-time","nullable":true},"settledOn":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true},"requestedBy":{"type":"string"},"reviewedBy":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"title":"TransferRequest"},"def-15":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"payload":{"type":"object","description":"The issuance request details captured at submission time.","properties":{"investorId":{"type":"string"},"securityId":{"type":"string"},"quantity":{"type":"string","description":"Number of shares as numeric string"},"issuanceDate":{"type":"string","description":"Issuance date (ISO date or date-time)"},"recipientType":{"type":"string","description":"Why the issuance was submitted (e.g. PRIMARY_OFFERING)"},"costBasis":{"type":"string","nullable":true,"description":"Cost basis as numeric string"},"notes":{"type":"string","nullable":true},"idempotencyKey":{"type":"string","nullable":true}},"additionalProperties":true},"securityId":{"type":"string"},"investorId":{"type":"string"},"shares":{"type":"string"},"pricePerShare":{"type":"string","nullable":true},"consideration":{"type":"string","nullable":true},"memo":{"type":"string","nullable":true},"idempotencyKey":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"requestedBy":{"type":"string"},"reviewedBy":{"type":"string","nullable":true},"rejectionReason":{"type":"string","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"webhookId":{"type":"string","nullable":true,"description":"Correlation id echoed on submission responses — matches the issuanceId in ta.issuance.* webhook events"}},"title":"IssuanceRequest"},"def-16":{"type":"object","properties":{"id":{"type":"string"},"investorId":{"type":"string"},"investorName":{"type":"string","nullable":true,"description":"Name of the owning investor"},"documentType":{"type":"string"},"fileName":{"type":"string","nullable":true,"description":"Sanitized original filename"},"fileSize":{"type":"integer","nullable":true,"description":"File size in bytes"},"status":{"type":"string","nullable":true,"description":"Upload status (lowercased): pending / confirmed / rejected"},"uploadedBy":{"type":"string","nullable":true,"description":"Identity that initiated the upload"},"label":{"type":"string","nullable":true},"storageUrl":{"type":"string","nullable":true},"mimeType":{"type":"string","nullable":true},"sizeBytes":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"title":"Document"},"def-17":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"title":"WebhookSubscription"}}},"paths":{"/api/v1/investors/":{"get":{"summary":"List investors","tags":["Investors"],"description":"Returns a paginated list of investors for the authenticated issuer.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false,"description":"Results per page"},{"schema":{"type":"string","enum":["NOT_STARTED","PENDING","APPROVED","REJECTED","EXPIRED"]},"in":"query","name":"kycStatus","required":false,"description":"Filter by KYC status"},{"schema":{"type":"string","enum":["NONE","PENDING","VERIFIED","EXPIRED"]},"in":"query","name":"accreditationStatus","required":false,"description":"Filter by accreditation status"},{"schema":{"type":"string","enum":["INDIVIDUAL","CORPORATION","LLC","PARTNERSHIP","TRUST","FUND","DAO","OTHER"]},"in":"query","name":"entityType","required":false,"description":"Filter by entity type"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by name or email"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-10"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"post":{"summary":"Create investor","tags":["Investors"],"description":"Creates a new investor record for the authenticated issuer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Investor full name or entity name"},"email":{"type":"string","format":"email","nullable":true,"description":"Contact email address"},"entityType":{"type":"string","enum":["INDIVIDUAL","CORPORATION","LLC","PARTNERSHIP","TRUST","FUND","DAO","OTHER"],"default":"INDIVIDUAL","description":"Legal entity type"},"jurisdiction":{"type":"string","maxLength":100,"nullable":true,"description":"Country or state of jurisdiction"},"taxId":{"type":"string","maxLength":100,"nullable":true,"description":"Tax identification number (EIN, SSN, etc.)"},"walletAddress":{"type":"string","maxLength":200,"nullable":true,"description":"Blockchain wallet address"},"sharesOwned":{"type":"string","pattern":"^\\d+$","description":"Total shares owned — non-negative integer as string"},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","APPROVED","REJECTED","EXPIRED"],"default":"NOT_STARTED","description":"KYC verification status"},"accreditationStatus":{"type":"string","enum":["NONE","PENDING","VERIFIED","EXPIRED"],"default":"NONE","description":"Investor accreditation status"},"notes":{"type":"string","maxLength":5000,"nullable":true,"description":"Internal notes"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-10"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/investors/{id}":{"get":{"summary":"Get investor","tags":["Investors"],"description":"Returns a single investor by ID for the authenticated issuer.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Investor ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-10"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"patch":{"summary":"Update investor","tags":["Investors"],"description":"Partially updates an investor record. All body fields are optional.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","APPROVED","REJECTED","EXPIRED"],"description":"KYC verification status"},"kycVerifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"Date KYC was verified"},"kycExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Date KYC expires"},"accreditationStatus":{"type":"string","enum":["NONE","PENDING","VERIFIED","EXPIRED"],"description":"Investor accreditation status"},"accreditationVerifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"Date accreditation was verified"},"accreditationExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Date accreditation expires"},"walletAddress":{"type":"string","maxLength":200,"nullable":true,"description":"Blockchain wallet address"},"sharesOwned":{"type":"string","pattern":"^\\d+$","description":"Total shares owned — non-negative integer as string"},"notes":{"type":"string","maxLength":5000,"nullable":true,"description":"Internal notes"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Investor ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-10"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/investors/{id}/holdings":{"get":{"summary":"Get investor holdings","tags":["Investors"],"description":"Returns all security holdings for a single investor.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Investor ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-11"}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/securities/":{"get":{"summary":"List securities","tags":["Securities"],"description":"Returns a paginated list of securities for the authenticated issuer.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false,"description":"Results per page"},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Filter by security status"},{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Filter by security type"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-12"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/securities/{id}":{"get":{"summary":"Get security","tags":["Securities"],"description":"Returns a single security by ID, including the top 10 holders.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Security ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-12"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/securities/{id}/captable":{"get":{"summary":"Get cap table","tags":["Securities"],"description":"Returns paginated list of all shareholders for this security, ordered by shares descending.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"in":"query","name":"perPage","required":false,"description":"Results per page"},{"schema":{"type":"boolean","default":true},"in":"query","name":"minBalance","required":false,"description":"When true (default), excludes holders with a zero balance"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Security ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-13"}},"pagination":{"$ref":"#/components/schemas/def-0"},"totalShares":{"type":"string","nullable":true,"description":"Total shares outstanding for this security"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/securities/{id}/holders":{"get":{"summary":"List security holders","tags":["Securities"],"description":"Alias for GET /:id/captable. Returns the same paginated shareholder list.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"in":"query","name":"perPage","required":false,"description":"Results per page"},{"schema":{"type":"boolean","default":true},"in":"query","name":"minBalance","required":false,"description":"When true (default), excludes holders with a zero balance"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Security ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-13"}},"pagination":{"$ref":"#/components/schemas/def-0"},"totalShares":{"type":"string","nullable":true,"description":"Total shares outstanding for this security"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/transfers/":{"get":{"summary":"List transfer requests","tags":["Transfers"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"perPage","required":false},{"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"securityId","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"fromDate","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"toDate","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-14"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"post":{"summary":"Submit transfer request","tags":["Transfers"],"description":"Submits a book-entry transfer from one investor to another. The transfer is queued as PENDING until approved by a TA admin. Supports an optional `idempotencyKey` to prevent duplicate submissions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromInvestorId","securityId","quantity"],"properties":{"fromInvestorId":{"type":"string"},"toInvestorId":{"type":"string"},"securityId":{"type":"string"},"quantity":{"type":"string","description":"Numeric string (integer or decimal)"},"price":{"type":"string","description":"Optional price per unit as numeric string"},"idempotencyKey":{"type":"string"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-14"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/transfers/{id}":{"get":{"summary":"Get transfer request","tags":["Transfers"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-14"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/transfers/batch":{"post":{"summary":"Batch submit transfer requests","tags":["Transfers"],"description":"Submit up to 500 transfer requests in a single call. Each item supports its own `idempotencyKey`. Returns individual results per item.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idempotencyId","transfers"],"properties":{"idempotencyId":{"type":"string"},"transfers":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["idempotencyId","fromInvestorId","securityId","quantity"],"properties":{"idempotencyId":{"type":"string"},"fromInvestorId":{"type":"string"},"toInvestorId":{"type":"string"},"toInvestor":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"entityType":{"type":"string"},"jurisdiction":{"type":"string"}}},"securityId":{"type":"string"},"quantity":{"type":"string"},"price":{"type":"string"},"matchedOn":{"type":"string","format":"date-time"},"settledOn":{"type":"string","format":"date-time"}}}}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string"},"submitted":{"type":"integer"},"duplicates":{"type":"integer"},"transfers":{"type":"array","items":{"type":"object","properties":{"idempotencyId":{"type":"string"},"transferId":{"type":"string"},"status":{"type":"string"}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/transfers/{id}/status":{"patch":{"summary":"Approve or reject transfer","tags":["Transfers"],"description":"Approve or reject a PENDING transfer request. Approval executes the balance change atomically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","reject"]},"reviewNote":{"type":"string","maxLength":2000}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-14"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/issuances/":{"get":{"summary":"List issuance requests","tags":["Issuances"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"perPage","required":false},{"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"securityId","required":false},{"schema":{"type":"string"},"in":"query","name":"investorId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-15"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"post":{"summary":"Submit issuance request","tags":["Issuances"],"description":"Queues a primary share issuance request for approval. Equivalent to Vertalo's TaRequest. The issuance is PENDING until a TA admin approves it, at which point shares are credited to the investor.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["investorId","securityId","quantity"],"properties":{"investorId":{"type":"string"},"securityId":{"type":"string"},"quantity":{"type":"string","description":"Number of shares as numeric string"},"costBasis":{"type":"string","description":"Cost basis as numeric string"},"issuanceDate":{"type":"string","format":"date-time"},"idempotencyKey":{"type":"string"},"notes":{"type":"string","maxLength":2000},"recipientType":{"type":"string","enum":["PRIMARY_OFFERING","EMPLOYEE_GRANT","VENDOR_PAYMENT","CONSULTANT_GRANT","BOARD_COMPENSATION","CONVERSION","OTHER"],"description":"Why this issuance is being submitted — primary offering vs. employee/vendor/consultant grant, etc. Defaults to PRIMARY_OFFERING when omitted."}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-15"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/issuances/{id}":{"get":{"summary":"Get issuance request","tags":["Issuances"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-15"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/issuances/{id}/approve":{"post":{"summary":"Approve issuance request","tags":["Issuances"],"description":"Approves a PENDING issuance request and executes the share credit to the investor's balance atomically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewNote":{"type":"string","maxLength":2000}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-15"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/issuances/{id}/reject":{"post":{"summary":"Reject issuance request","tags":["Issuances"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rejectionReason":{"type":"string","maxLength":2000}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-15"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/documents/":{"get":{"summary":"List documents","tags":["Documents"],"parameters":[{"schema":{"type":"integer","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"maximum":100},"in":"query","name":"perPage","required":false},{"schema":{"type":"string"},"in":"query","name":"investorId","required":false},{"schema":{"type":"string"},"in":"query","name":"documentType","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-16"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}}}}},"/api/v1/documents/{id}":{"get":{"summary":"Get document","tags":["Documents"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-16"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"delete":{"summary":"Delete document","tags":["Documents"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"No content"},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/documents/{id}/download":{"get":{"summary":"Get short-lived download URL","tags":["Documents"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/documents/upload-url":{"post":{"summary":"Request document upload URL","tags":["Documents"],"description":"Generates a v4-signed PUT URL bound to the per-issuer Cloud HSM key and returns a confirmation token. The URL is valid for 15 minutes; the client uploads the file directly to GCS, then calls PUT /upload/:uploadToken to finalize.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["investorId","documentType","fileName","mimeType","fileSize"],"properties":{"investorId":{"type":"string"},"documentType":{"type":"string","enum":["KYC_ID","ACCREDITATION","SUBSCRIPTION_AGREEMENT","TAX_FORM","OTHER"]},"fileName":{"type":"string"},"mimeType":{"type":"string"},"fileSize":{"type":"integer"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"documentId":{"type":"string"},"uploadUrl":{"type":"string"},"uploadToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"requiredHeaders":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/documents/upload/{uploadToken}":{"put":{"summary":"Confirm document upload","tags":["Documents"],"description":"Confirms a document upload. The body is empty in Phase 2 — the API constructs the storage path internally and verifies the object exists at the expected GCS key. Idempotent.","parameters":[{"schema":{"type":"string"},"in":"path","name":"uploadToken","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-16"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"410":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/webhooks/events":{"get":{"summary":"List available webhook events","tags":["Webhooks"],"description":"Returns all webhook event types that can be subscribed to. No authentication required.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/v1/webhooks/":{"get":{"summary":"List webhook subscriptions","tags":["Webhooks"],"parameters":[{"schema":{"type":"integer"},"in":"query","name":"page","required":false},{"schema":{"type":"integer"},"in":"query","name":"perPage","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-17"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"post":{"summary":"Create webhook subscription","tags":["Webhooks"],"description":"Creates a new webhook subscription. A secret is auto-generated if not provided. The secret is returned ONCE on creation — store it securely. Use it to verify incoming webhook signatures (HMAC-SHA256).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"Must be an HTTPS URL"},"events":{"type":"array","items":{"type":"string"},"minItems":1},"secret":{"type":"string"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/def-17"},{"type":"object","properties":{"secret":{"type":"string"},"_note":{"type":"string"}}}]}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/webhooks/{id}":{"patch":{"summary":"Update webhook subscription","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-17"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}},"delete":{"summary":"Delete webhook subscription","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"No content"},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/webhooks/{id}/test":{"post":{"summary":"Send test webhook event","tags":["Webhooks"],"description":"Queues a `ta.test` event for delivery to the subscription's URL to verify the endpoint is reachable and the signature verification logic is correct. Delivery is asynchronous (fire-and-forget) — the response confirms the event was queued, not that the remote endpoint accepted it.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","example":"Test event queued for delivery"},"event":{"type":"string","example":"ta.test"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/settlements/":{"get":{"summary":"List settlement instructions","tags":["Settlements"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Submit settlement instruction","tags":["Settlements"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/{id}":{"get":{"summary":"Get settlement instruction","tags":["Settlements"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/{id}/approve":{"post":{"summary":"Approve settlement instruction","tags":["Settlements"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/{id}/reject":{"post":{"summary":"Reject settlement instruction","tags":["Settlements"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/{id}/cancel":{"post":{"summary":"Cancel settlement instruction","tags":["Settlements"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/{id}/execute":{"post":{"summary":"Manually execute approved settlement","tags":["Settlements"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/{id}/reverse":{"post":{"summary":"Create reversal of an executed settlement","tags":["Settlements"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/settlements/configs":{"get":{"summary":"List settlement configs (issuer + per-security)","tags":["Settlements"],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Upsert settlement config (issuer default or per-security override)","tags":["Settlements"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/investor-accounts/":{"get":{"summary":"List investor accounts","tags":["InvestorAccounts"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create investor account (omnibus parent or sub-account)","tags":["InvestorAccounts"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/investor-accounts/{id}/reconcile":{"post":{"summary":"Run omnibus reconciliation snapshot (parent vs Σ(children))","tags":["InvestorAccounts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/dividends/":{"get":{"summary":"List dividends","tags":["Dividends"],"description":"All dividends for the issuer bound to the API key, newest first.","responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Declare a dividend (enters tZERO review)","tags":["Dividends"],"description":"Creates the dividend in PENDING_REVIEW. A tZERO transfer-agent reviewer approves or rejects it under a Rule 17Ad-2 SLA timer; status changes are delivered via ta.dividend.* webhooks. Requires an Idempotency-Key header.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/dividends/{id}":{"get":{"summary":"Get a dividend with payment rollups","tags":["Dividends"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/dividends/{id}/funding":{"get":{"summary":"Get USDC funding deposit instructions for a CASH dividend","tags":["Dividends"],"description":"After a CASH dividend is approved and frozen, returns where and how much USDC to deposit. `requiredBaseUnits` is the ON-CHAIN cash the pool needs — it EXCLUDES holders who elected reinvestment (DRIP, retained by the fund) or off-chain clearing, so it can be less than the declared total. Fund this exact amount to the deposit address; overfunding is held as a refund.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/dividends/{id}/reconciliation":{"get":{"summary":"Reconcile a dividend: declared vs distributed","tags":["Dividends"],"description":"Proves every declared base unit is accounted for across payout modes (USDC paid, reinvested cost, reinvest residual, clearing-settled), with no drift and no open/failed entitlements. `reconciled:true` means the dividend is fully and correctly distributed.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/dividends/payment-tokens":{"get":{"summary":"List approved payment tokens for a security","tags":["Dividends"],"description":"The allowlisted tokens (per the USDC-only policy) accepted as dividendTokenAddress for on-chain CASH dividends on the security's chain and network.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/dividends/{id}/cancel":{"post":{"summary":"Cancel a dividend","tags":["Dividends"],"description":"PENDING_REVIEW: withdrawn before review. DECLARED (not yet executed): cancelled. Executed on-chain dividends must be cancelled by the transfer agent (claim-contract cancellation) — contact tZERO. Requires Idempotency-Key.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/corporate-actions/":{"get":{"summary":"List corporate actions","tags":["Corporate Actions"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Declare a corporate action (enters tZERO review)","tags":["Corporate Actions"],"description":"Creates the action in PENDING_REVIEW under a Rule 17Ad-2 SLA timer. Status changes via ta.corporate_action.* webhooks. Requires Idempotency-Key.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/corporate-actions/{id}":{"get":{"summary":"Get a corporate action","tags":["Corporate Actions"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/corporate-actions/{id}/cancel":{"post":{"summary":"Cancel a corporate action","tags":["Corporate Actions"],"description":"PENDING_REVIEW: withdrawn. ANNOUNCED (not executed): cancelled. Later states are transfer-agent operations. Requires Idempotency-Key.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/proposals/":{"get":{"summary":"List proposals","tags":["Proposals"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a voting proposal (enters tZERO review)","tags":["Proposals"],"description":"Creates the proposal in PENDING_REVIEW under a Rule 17Ad-2 SLA timer. On approval, voting opens (ON_CHAIN proposals are anchored with their record block + terms hash first). Investors vote in their own portal accounts — votes cannot be submitted through this API. Requires Idempotency-Key.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/proposals/{id}":{"get":{"summary":"Get a proposal with running tallies","tags":["Proposals"],"description":"Option-level votesCount and sharesVoted update live while voting is OPEN.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/proposals/{id}/results":{"get":{"summary":"Get final results with on-chain anchors","tags":["Proposals"],"description":"Available once voting has closed and the tally is final (status TALLIED). For ON_CHAIN proposals includes the open/close anchor transaction hashes, the ballots Merkle root, and the canonical tally hash.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/proposals/{id}/cancel":{"post":{"summary":"Cancel a proposal","tags":["Proposals"],"description":"PENDING_REVIEW: withdrawn. OPEN: voting is terminated and the proposal is CANCELLED (ON_CHAIN proposals receive a termination close-anchor). Requires Idempotency-Key.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/iso/fund-orders/subscriptions":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/iso/fund-orders/redemptions":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/iso/fund-orders/subscriptions/cancel":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/iso/fund-orders/redemptions/cancel":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tokens/":{"get":{"summary":"List tokens","tags":["Tokens"],"description":"Returns a paginated list of token configurations for the authenticated issuer, each with its on-chain deployments.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false,"description":"Results per page"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeDelisted","required":false,"description":"Include delisted tokens"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-2"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/tokens/{id}":{"get":{"summary":"Get token","tags":["Tokens"],"description":"Returns a single token configuration (with deployments) owned by the authenticated issuer.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Token configuration ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-2"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/deployments/":{"get":{"summary":"List deployments","tags":["Deployments"],"description":"Returns a paginated list of on-chain deployments for the authenticated issuer. Optionally filter by tokenConfigId.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false,"description":"Results per page"},{"schema":{"type":"string"},"in":"query","name":"tokenConfigId","required":false,"description":"Filter to one token configuration"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-3"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/deployments/{id}":{"get":{"summary":"Get deployment","tags":["Deployments"],"description":"Returns a single deployment owned by the authenticated issuer.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Deployment ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-3"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/deployments/{id}/operations":{"get":{"summary":"List deployment operations","tags":["Deployments"],"description":"Returns the on-chain operation history (mint, burn, transfer, role changes, …) for a deployment owned by the authenticated issuer.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Deployment ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-4"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/vaults":{"get":{"summary":"List custody vaults","tags":["Vaults"],"description":"Returns the custody vaults owned by the authenticated issuer, each with its asset wallets.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-6"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/vaults/{id}":{"get":{"summary":"Get custody vault","tags":["Vaults"],"description":"Returns a single custody vault (with wallets) owned by the authenticated issuer.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Vault ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-6"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/transfers":{"get":{"summary":"List custody transfers","tags":["Custody Transfers"],"description":"Returns custody transfers across the authenticated issuer's vaults. Optionally filter by vaultId.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false},{"schema":{"type":"string"},"in":"query","name":"vaultId","required":false,"description":"Filter to one vault"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-7"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/whitelist":{"get":{"summary":"List whitelisted addresses","tags":["Whitelist"],"description":"Returns the external addresses whitelisted by the authenticated issuer, with their assets.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"perPage","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/def-9"}},"pagination":{"$ref":"#/components/schemas/def-0"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/whitelist/{id}":{"get":{"summary":"Get whitelisted address","tags":["Whitelist"],"description":"Returns a single whitelisted address (with assets) owned by the authenticated issuer.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Whitelisted address ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-9"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/vaults/{id}/balances":{"get":{"summary":"Get live vault balances","tags":["Vaults"],"description":"Returns live custody-provider balances for a vault owned by the authenticated issuer. Returns 503 if custody is not configured in this environment.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Vault ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/supported-assets":{"get":{"summary":"List supported assets","tags":["Custody Assets"],"description":"Lists the assets supported by the custody provider. Returns 503 if custody is not configured in this environment.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/validate-address":{"post":{"summary":"Validate an address","tags":["Custody Assets"],"description":"Validates a blockchain address for the given asset via the custody provider. Read-only despite the POST verb. Returns 503 if custody is not configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assetId","address"],"properties":{"assetId":{"type":"string","description":"Custody asset id (e.g. ETH_TEST5)"},"address":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody/estimate-fee/{assetId}":{"get":{"summary":"Estimate network fee","tags":["Custody Assets"],"description":"Estimates the network fee for an asset via the custody provider. Returns 503 if custody is not configured.","parameters":[{"schema":{"type":"string"},"in":"path","name":"assetId","required":true,"description":"Custody asset id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/api/v1/custody-accounts/accounts":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/accounts/{accountId}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/accounts/{accountId}/positions":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/accounts/{accountId}/deposit-addresses":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/accounts/{accountId}/transfers":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/transfers/{transferId}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"transferId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/transfers/{transferId}/approvals":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"transferId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/accounts/{accountId}/whitelist":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/webhooks":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/webhooks/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/events":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/custody-accounts/events/{id}/replay":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/sessions":{"post":{"summary":"Mint an embed-session token","tags":["SubRed Embed"],"description":"Server-to-server. Issues a short-lived, investor-scoped token for the embeddable plugin. The issuer is taken from the API key; the investor must belong to it.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/me":{"get":{"summary":"Resolve the current embed session","tags":["SubRed Embed"],"description":"Returns the issuer, investor, and scopes carried by the embed-session token.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/securities":{"get":{"summary":"List eligible securities","tags":["SubRed Embed"],"description":"Securities the embed-session investor may currently subscribe to (ACTIVE link, priced NAV, ALLOW eligibility).","responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/wallet":{"get":{"summary":"Get investor wallet + buying power","tags":["SubRed Embed"],"description":"The embed-session investor's bound custodial wallet, on-chain balances, fund URI, and derived buying power. Read-only — never provisions. Pass `securityId` to view the wallet for that security's settlement rail (an EVM security returns its per-chain custody wallet + ERC-20 balance instead of the Stellar wallet).","responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/subscriptions":{"post":{"summary":"Subscribe (buy) with USDC","tags":["SubRed Embed"],"description":"Places a held USDC subscription for the embed-session investor and returns deposit instructions.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/subscriptions/{instructionId}/pay-from-balance":{"post":{"summary":"Pay a subscription from custody balance","tags":["SubRed Embed"],"description":"App-signed USDC transfer from the investor's custodial wallet to the order's deposit address. Memo-idempotent.","parameters":[{"schema":{"type":"string"},"in":"path","name":"instructionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/orders/{instructionId}/status":{"get":{"summary":"Order status","tags":["SubRed Embed"],"description":"Live settlement status for one of the embed-session investor's own orders.","parameters":[{"schema":{"type":"string"},"in":"path","name":"instructionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/redemptions":{"post":{"summary":"Redeem for USDC","tags":["SubRed Embed"],"description":"Places a held USDC redemption for the embed-session investor; USDC is paid to their own wallet.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/subred/embed/securities/{securityId}/election":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"securityId","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"securityId","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.t0direct.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Investors","description":"Investor KYC, accreditation, and holdings management"},{"name":"Securities","description":"Security and instrument definitions"},{"name":"Transfers","description":"Book-entry transfer requests (secondary)"},{"name":"Issuances","description":"Primary share issuance requests"},{"name":"Documents","description":"Investor document upload and retrieval"},{"name":"Dividends","description":"Dividend declarations (cash & stock) — review-gated; on-chain execution via the dividend claim contract"},{"name":"Corporate Actions","description":"Splits, mergers and other corporate actions — review-gated; on-chain splits broadcast via Fireblocks"},{"name":"Proposals","description":"Shareholder voting — proposal creation and results; off-chain or on-chain (anchored) voting modes"},{"name":"Webhooks","description":"Webhook subscription management and event delivery"},{"name":"Tokens","description":"Token configurations — the issuer's token blueprints"},{"name":"Deployments","description":"On-chain instances of tokens and their operation history"},{"name":"Vaults","description":"Custody vaults and their asset wallets"},{"name":"Custody Transfers","description":"Transfers of assets out of custody vaults"},{"name":"Whitelist","description":"Approved external addresses for custody transfers"},{"name":"Custody Assets","description":"Supported assets, address validation, and fee estimation (live)"}]}