> ## Documentation Index > Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt > Use this file to discover all available pages before exploring further. # Get transaction by ID > Retrieves a single transaction by ID. ## OpenAPI ````yaml /api-reference/openapi.yaml get /transactions/{transactionId} openapi: 3.0.3 info: title: Polygon OMS Public API version: v26.10.01-0001 description: >- Unified API for moving money between crypto and fiat. Three ways to move money: Transactions (instant, wallet or card funded, including Cash-In for in-person cash deposits), Deposit Addresses (reusable crypto deposit configurations), and Virtual Accounts (dedicated bank accounts that auto-convert fiat to crypto). Standard transactions follow a two-step flow: create a Quote (pricing), then create a Transaction (execution). Cash-in codes generate a one-time deposit code for in-person cash deposits at retail locations. contact: name: Polygon OMS url: https://oms.polygon.technology servers: - url: https://sandbox-api.polygon.technology/v0.13 description: Sandbox - url: https://api.polygon.technology/v0.13 description: Production security: - BearerAuth: [] tags: - name: Auth description: Authentication via OMS API key and secret - name: Customers description: Customer management and KYC - name: Customer - name: Wallet - name: Quote - name: Transaction - name: CashIns - name: CashLocation - name: Sandbox - name: VirtualAccount - name: Counterparty - name: ExternalAccount - name: Reference - name: DepositAddress paths: /transactions/{transactionId}: get: tags: - Transaction summary: Get transaction by ID description: Retrieves a single transaction by ID. operationId: getTransaction parameters: - name: transactionId in: path required: true description: Transaction ID (`txn_` prefix). schema: type: string responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Transaction' examples: Failed transfer, inbound returned to the registered wallet: summary: Failed transfer, inbound returned to the registered wallet value: id: txn_mmbdyjd3r0z92y1zwck56anv0r object: transaction sourceToDestination: cryptoToCrypto status: failed subStatus: failed.returnComplete customerId: cst_vfa0nxw6zvyws9g237jrxn4y7k precursor: type: quote id: qt_6yd7gwfxaa13m83sepnzrmqnj2 source: party: relationship: customer id: cst_vfa0nxw6zvyws9g237jrxn4y7k name: Jane Smith type: walletCrypto category: crypto id: wlt_5h4jzzpr9xre3bamd9ca7qyghn asset: usdc network: polygon displayName: '0x7B3A9F2C4D1eA8bf6390cE5D2b7fA104c8e3D9B1' destination: party: relationship: externalRegistered id: ctp_yp5z8m7n22svc0vh6edqgcfdat name: Alice Smith type: walletExternal category: crypto id: ext_95863ktcdhw27ze8hxgybb24n9 asset: usdc network: base displayName: '0xbEeF4A2C891d56e72B67a3f21d0cF94f1D7c5911' payoutOrigin: type: blockchain id: wlt_5h4jzzpr9xre3bamd9ca7qyghn accountHolder: null accountHolderName: null pricing: source: asset: usdc amountGross: '100.00' amountNet: '100.00' destination: asset: usdc amountGross: '100.00' amountNet: '100.00' fees: [] exchangeRate: '1.0000' fixedAmountSide: source sponsorGas: true sponsorGasCost: '0.00' tracking: [] error: code: bridgeTimeout message: Bridge transaction timed out after 30 minutes. occurredAt: '2026-03-14T19:35:00Z' recoverable: false createdAt: '2026-03-14T19:00:00Z' updatedAt: '2026-03-14T19:35:00Z' Deposit-address inbound from an unrecognized sender, awaiting attribution: summary: >- Deposit-address inbound from an unrecognized sender, awaiting attribution value: id: txn_x9waqqeg1ng6v32c5142zfp89d object: transaction sourceToDestination: cryptoToFiatAccount status: awaitingAction subStatus: awaitingAction.awaitingSenderAttribution customerId: cst_vfa0nxw6zvyws9g237jrxn4y7k precursor: type: depositAddress id: da_r8f126hqwm3x6j5k00qsaysf4c source: party: relationship: externalUnregistered id: null name: null type: walletExternal category: crypto id: null asset: usdc network: polygon displayName: '0xeB3eCfb244E94a407bfb1EEcFEDe27D920cc00F5' details: blockchainAddress: '0xeB3eCfb244E94a407bfb1EEcFEDe27D920cc00F5' destination: party: relationship: customer id: cst_vfa0nxw6zvyws9g237jrxn4y7k name: Jane Smith type: bankUs category: fiatAccount id: ext_cc35pa5vgrq1tpsqm4bxy2dkrg asset: usd network: ach secCode: web displayName: ••••1234 pricing: source: asset: usdc amountGross: '250.00' amountNet: '250.00' destination: asset: usd amountGross: '250.00' amountNet: '250.00' fees: [] exchangeRate: '1.0000' fixedAmountSide: source sponsorGas: true sponsorGasCost: '0.00' tracking: [] hold: type: senderAttribution required: true since: '2026-05-15T17:32:48Z' deadline: '2026-06-14T17:32:48Z' matchableExternalAccountCriteria: type: walletExternal blockchainAddress: '0xeB3eCfb244E94a407bfb1EEcFEDe27D920cc00F5' networkFamily: evm createdAt: '2026-05-15T17:32:48Z' updatedAt: '2026-05-15T17:32:48Z' Cash payout with a pickup code ready at a retail location: summary: Cash payout with a pickup code ready at a retail location value: id: txn_t21b4031yen78cqx2t93crbs66 object: transaction sourceToDestination: cryptoToCash status: processing subStatus: processing.cashPickupReady customerId: cst_vfa0nxw6zvyws9g237jrxn4y7k precursor: type: quote id: qt_3qj8x54e73641hrabft05xc6fv source: party: relationship: customer id: cst_vfa0nxw6zvyws9g237jrxn4y7k name: Jane Smith type: walletCrypto category: crypto id: wlt_5h4jzzpr9xre3bamd9ca7qyghn asset: usdc network: polygon displayName: '0x7B3A9F2C4D1eA8bf6390cE5D2b7fA104c8e3D9B1' destination: party: relationship: customer id: cst_vfa0nxw6zvyws9g237jrxn4y7k name: Jane Smith type: cash category: cash asset: usd cashLocationId: loc_01H9Xd displayName: 'Walmart #2517' pickupCode: '8847162' pricing: source: asset: usdc amountGross: '100.00' amountNet: '100.00' destination: asset: usd amountGross: '100.00' amountNet: '100.00' fees: [] exchangeRate: '1.0000' fixedAmountSide: destination sponsorGas: true sponsorGasCost: '0.00' tracking: [] createdAt: '2026-03-14T20:00:00Z' updatedAt: '2026-03-14T20:00:30Z' expiresAt: '2026-03-14T21:00:00Z' Completed payout from an OMS wallet to a US bank account: summary: Completed payout from an OMS wallet to a US bank account value: id: txn_qv6ch9rjv7t8nncezke4s10a3z object: transaction sourceToDestination: cryptoToFiatAccount status: completed subStatus: completed.settled customerId: cst_vfa0nxw6zvyws9g237jrxn4y7k precursor: type: quote id: qt_0gq9aesz4wb5etdv88z1j61qcm source: party: relationship: customer id: cst_vfa0nxw6zvyws9g237jrxn4y7k name: Jane Smith type: walletCrypto category: crypto id: wlt_5h4jzzpr9xre3bamd9ca7qyghn asset: usdc network: polygon displayName: '0x7B3A9F2C4D1eA8bf6390cE5D2b7fA104c8e3D9B1' destination: party: relationship: externalRegistered id: ctp_yp5z8m7n22svc0vh6edqgcfdat name: Alice Smith type: bankUs category: fiatAccount id: ext_fky491gakzj0dd46qb6whsr2vq asset: usd network: ach secCode: web displayName: ••••1234 payoutOrigin: type: bank id: va_e6nfr4q5jj9bwgb1pyx70wzxta accountHolder: customer accountHolderName: Jane Smith pricing: source: asset: usdc amountGross: '100.00' amountNet: '100.00' destination: asset: usd amountGross: '100.00' amountNet: '100.00' fees: [] exchangeRate: '1.0000' fixedAmountSide: source sponsorGas: true sponsorGasCost: '0.00' tracking: [] estimatedArrival: '2026-03-14T19:30:00Z' metadata: orderId: order_12345 createdAt: '2026-03-14T19:00:00Z' updatedAt: '2026-03-14T19:05:00Z' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/TransactionNotFoundErrorResponse' components: schemas: Transaction: type: object required: - id - object - status - subStatus - customerId - precursor - source - destination - pricing - tracking properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Transaction ID (`txn_` prefix). object: type: string enum: - transaction description: Resource type discriminator. Always "transaction". sourceToDestination: allOf: - $ref: '#/components/schemas/SourceToDestination' description: Corridor composite derived from the two sides. status: allOf: - $ref: '#/components/schemas/TransactionStatus' description: Current lifecycle status. See `subStatus` for finer granularity. subStatus: allOf: - $ref: '#/components/schemas/TransactionSubStatus' description: >- Status-scoped sub-state (e.g. `processing.fundsPulled`). Always present: each status carries a default member (e.g. `processing.initiated`) when no more specific value applies. customerId: allOf: - $ref: '#/components/schemas/typeId' description: >- The OMS customer that owns this record — the sender on a transaction (`cst_` prefix). customer: allOf: - $ref: '#/components/schemas/CustomerSummary' description: >- Display-safe summary of the owning customer (`customer.id` equals `customerId`) — lets a list row render without a second request. precursor: type: object allOf: - $ref: '#/components/schemas/Precursor' nullable: true description: >- What created this transaction, as a uniform `{type, id}` reference — dereference the resource by `id` for its full record. A custodial-wallet deposit renders `{type: walletDeposit, id: null}`. `null` remains only for a genuine out-of-band arrival with no recognised origin at all; the `manual` arm (`id: null`) is reserved for a future operator-initiated transaction, distinct from either. source: allOf: - $ref: '#/components/schemas/TransactionSide' description: 'The funding side: a typed instrument carrying identity and detail.' destination: allOf: - $ref: '#/components/schemas/TransactionDestination' description: 'The receiving side: a typed instrument plus `payoutOrigin`.' pricing: allOf: - $ref: '#/components/schemas/Pricing' description: Consolidated economics. tracking: type: array items: $ref: '#/components/schemas/TrackingEntry' description: >- Every rail identifier assigned to this transaction — blockchain tx hashes and Fedwire/SWIFT references (`uetr`, `imad`, `endToEndId`, `instructionId`) today; ACH/cash rail references planned. Ordered oldest-first by leg; within one leg the entries follow a fixed scheme order, not the moment each identifier was assigned. A re-driven wire payout replaces its previous wire's identifiers in place rather than appending them. `[]` until the first identifier is assigned. estimatedArrival: type: string format: date-time description: >- Estimated completion time. Present when the destination rail has a predictable settlement time (e.g. bank payouts and some crypto legs); null otherwise. error: allOf: - $ref: '#/components/schemas/SettlementError' description: >- Failure detail. Set when the transaction fails; includes refund or recovery state where applicable. hold: allOf: - $ref: '#/components/schemas/Hold' nullable: true description: >- The hold blocking this transaction while `status` is `awaitingAction`. Retained after it clears, with `resolvedAt` set and `required` false, so the reason stays visible. Absent if the transaction has never been held. metadata: type: object additionalProperties: type: string description: Free-form key-value pairs supplied at creation or update. createdAt: type: string format: date-time description: When the transaction was created. updatedAt: type: string format: date-time description: When the transaction was last updated. expiresAt: type: string format: date-time description: >- Expiry of the transaction's actionable window: present on auto-created transactions and on cash payouts (the pickup-code expiry), and retained after completion for audit. Null for other quote-initiated transactions. projectId: allOf: - $ref: '#/components/schemas/omsxProjectId' description: >- The owning project. Populated only on the cross-project admin endpoints (e.g. GET /admin/transactions/redrivable) so operators can tell which project a stranded transaction belongs to. Omitted on partner endpoints, where the project is implicit from the auth token. description: >- A single movement of money from a source to a destination. Created by accepting a quote, or generated automatically by a deposit address, virtual account, or cash-in. Track its progress with status. TransactionNotFoundErrorResponse: type: object required: - error - code - msg properties: error: type: string enum: - TransactionNotFound code: type: number enum: - 10231 msg: type: string enum: - transaction not found cause: type: string typeId: type: string pattern: >- ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ description: Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`. x-go-type: string SourceToDestination: type: string enum: - cryptoToCrypto - cryptoToCash - cryptoToFiatAccount - cashToCrypto - fiatAccountToCrypto - fiatAccountToFiatAccount description: >- Composite of source and destination instrument categories, inferred from each side. The cash corridors (`cryptoToCash`, `cashToCrypto`) are derived from a cash-pickup destination / cash-in source respectively; the rest map straight from the internal corridor type. TransactionStatus: type: string enum: - processing - awaitingAction - completed - failed description: >- Lifecycle of a transaction. processing: funds in motion. awaitingAction: non-terminal, blocked on developer/upstream/compliance (see `hold`); returns to processing once cleared. completed: delivered. failed: terminal failure. TransactionSubStatus: type: string enum: - processing.fundsPulled - processing.cashPickupReady - processing.underReview - completed.cashPickupCollected - completed.cashPickupExpired - awaitingAction.informationRequested - awaitingAction.awaitingSenderAttribution - awaitingAction.depositAddressFrozen - awaitingAction.depositAddressInactive - failed.attributionTimeout - failed.depositAddressFrozenTimeout - failed.depositAddressInactiveTimeout - failed.depositAddressClosed - processing.awaitingCryptoOut - processing.cryptoOut - processing.awaitingFiatOut - processing.fiatOut - processing.inboundPending - processing.inboundProcessing - failed.inboundFailed - failed.returnPending - failed.returnStarted - failed.returnComplete - failed.returnFailed - processing.initiated - completed.settled - failed.unspecified - failed.expired - failed.providerDeclined - failed.outboundFailed description: >- Granular sub-status in dotted form — the prefix before the dot is always the coarse `status`. Required and never null: `processing`, `completed` and `failed` each carry a default member (`processing.initiated`, `completed.settled`, `failed.unspecified`) emitted when no more specific value applies. `awaitingAction` has no default member: every `awaitingAction.*` value names a specific blocking reason and pairs with the transaction's `hold`: `awaitingAction.informationRequested` → `hold.type` `informationRequested`, `awaitingAction.awaitingSenderAttribution` → `senderAttribution`, `awaitingAction.depositAddressFrozen` → `depositAddressFrozen`, `awaitingAction.depositAddressInactive` → `depositAddressInactive`. Switch on `hold.type` to read the arm's detail fields. `failed.returnComplete` is one value for two outcomes — a crypto send-back and a bank return (an ACH or wire bounce plus clawback) — so do not read it as naming either one. New members may be added without an API version bump, so clients MUST tolerate unknown values by falling back to the prefix before the dot (the dotted form exists precisely for this). The values below are the complete set emitted by this release; a client that validates against this list, including one generated from this schema, must be updated before it can accept a new member. CustomerSummary: type: object required: - id - name properties: id: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer id (`cst_` prefix). name: type: string description: Customer display name. description: >- Display-safe summary of a customer — ID plus display name only. Enables one-request list rendering: a page of rows needs no per-row detail queries. Always the record's owning customer, not whichever side a party sits on. Precursor: type: object required: - type - id properties: type: type: string enum: - quote - depositAddress - virtualAccount - cashIn - manual - walletDeposit id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- `qt_` / `da_` / `va_` / `ci_`. Null for `manual` and `walletDeposit`. description: >- What created this transaction, as a uniform `{type, id}` reference. Dereference the resource by `id` for its full record — deposit instructions live on the Virtual Account / Deposit Address / Cash-In, not here. `id` is null only for `manual` (operator-initiated, no origin resource) and `walletDeposit` (a custodial-wallet deposit, no originating OMS resource). The `precursor` field on Transaction is itself nullable separately, for out-of-band arrivals with no originating OMS resource and no recognised origin. TransactionSide: type: object oneOf: - $ref: '#/components/schemas/WalletCryptoInstrument' - $ref: '#/components/schemas/WalletExternalInstrument' - $ref: '#/components/schemas/WalletFiatInstrument' - $ref: '#/components/schemas/BankUsInstrument' - $ref: '#/components/schemas/BankIbanInstrument' - $ref: '#/components/schemas/BankCanadaInstrument' - $ref: '#/components/schemas/CardInstrument' - $ref: '#/components/schemas/CashInstrument' discriminator: propertyName: type mapping: walletCrypto: '#/components/schemas/WalletCryptoInstrument' walletExternal: '#/components/schemas/WalletExternalInstrument' walletFiat: '#/components/schemas/WalletFiatInstrument' bankUs: '#/components/schemas/BankUsInstrument' bankIban: '#/components/schemas/BankIbanInstrument' bankCanada: '#/components/schemas/BankCanadaInstrument' card: '#/components/schemas/CardInstrument' cash: '#/components/schemas/CashInstrument' description: >- The source side of a transaction/quote (v0.10): a typed instrument carrying identity (`party`) and instrument detail. Amounts live only in `pricing`. TransactionDestination: type: object oneOf: - $ref: '#/components/schemas/WalletCryptoDestination' - $ref: '#/components/schemas/WalletExternalDestination' - $ref: '#/components/schemas/WalletFiatDestination' - $ref: '#/components/schemas/BankUsDestination' - $ref: '#/components/schemas/BankIbanDestination' - $ref: '#/components/schemas/BankCanadaDestination' - $ref: '#/components/schemas/CardDestination' - $ref: '#/components/schemas/CashDestination' discriminator: propertyName: type mapping: walletCrypto: '#/components/schemas/WalletCryptoDestination' walletExternal: '#/components/schemas/WalletExternalDestination' walletFiat: '#/components/schemas/WalletFiatDestination' bankUs: '#/components/schemas/BankUsDestination' bankIban: '#/components/schemas/BankIbanDestination' bankCanada: '#/components/schemas/BankCanadaDestination' card: '#/components/schemas/CardDestination' cash: '#/components/schemas/CashDestination' description: >- The destination side of a transaction/quote (v0.10): a typed instrument plus `payoutOrigin`. Amounts live only in `pricing`. Pricing: type: object required: - fees properties: source: allOf: - $ref: '#/components/schemas/PricingSide' description: Economics for the source side, denominated in the source asset. destination: allOf: - $ref: '#/components/schemas/PricingSide' description: >- Economics for the destination side, denominated in the destination asset. fees: type: array items: $ref: '#/components/schemas/PricingFee' description: >- Every fee deducted across both sides. `[]` when there are none — never omitted, never null. exchangeRate: type: string description: >- Mid-market rate between source and destination assets. Identity: source.amountNet × exchangeRate = destination.amountGross. fixedAmountSide: type: string enum: - source - destination description: >- The side you set `amount` on when creating the quote. OMS calculated the other side. sponsorGas: type: boolean description: >- When true, OMS absorbs the destination gas cost. Currently always true. sponsorGasCost: type: string description: >- Gas absorbed by the developer when sponsorGas is true. Currently always `0.00`. description: >- Consolidated economics for a quote/transaction: per-side amounts, a flat fee list, the mid-market rate, and gas sponsorship, all in one place. TrackingEntry: type: object required: - scheme - value - leg properties: scheme: type: string description: >- Identifier kind. Emitted today: "txHash" (on-chain hash), "uetr", "imad", "endToEndId", "instructionId" (Fedwire/SWIFT rail identifiers). OPEN — clients must tolerate an unrecognised scheme. `tracking` is an ordered list, not a set: no combination of fields is unique. The same scheme repeats once per leg that carries such an identifier (a fiat-in → fiat-out payment has a different `uetr` on `source` and on `destination`) and again for each superseded attempt that survives as its own leg. Iterate it; do not index it. value: type: string description: The identifier itself, verbatim as assigned by the rail/vendor. network: type: string description: >- Network the identifier was assigned on (e.g. "polygon", "ach", "swift") — same vocabulary as instrument `network` fields. Absent when the identifier is not network-scoped. leg: type: string enum: - source - destination - return description: Which leg of the transaction this identifier belongs to. assignedBy: type: string description: >- The operator or partner that assigned this identifier, when known — e.g. `erebor`, `coinme`. Open — treat the string as free-form rather than a fixed set. Absent when the assigner is not resolvable. url: type: string description: >- Deep link to view this identifier on the rail's own explorer, when one is known. description: >- One network-assigned identifier. An array of tagged entries rather than a keyed map: the same scheme can repeat across legs, and new schemes are additive with no schema change. SettlementError: type: object required: - code - message - occurredAt - recoverable properties: code: type: string description: Machine-readable error code. Never a provider's own code. message: type: string description: Human-readable detail. Never names a provider. occurredAt: type: string format: date-time description: When the error occurred. recoverable: type: boolean description: Whether the failure can be recovered. manualRecovery: allOf: - $ref: '#/components/schemas/ManualRecovery' description: >- Populated only for terminal failures with no resolved refund/return path (v0.11). description: >- Details of an asynchronous settlement failure on a transaction (e.g. a downstream payout that failed after the initial request succeeded). Present only once a failure has occurred. Hold: type: object oneOf: - $ref: '#/components/schemas/HoldInformationRequested' - $ref: '#/components/schemas/HoldSenderAttribution' - $ref: '#/components/schemas/HoldDepositAddressFrozen' - $ref: '#/components/schemas/HoldDepositAddressInactive' discriminator: propertyName: type mapping: informationRequested: '#/components/schemas/HoldInformationRequested' senderAttribution: '#/components/schemas/HoldSenderAttribution' depositAddressFrozen: '#/components/schemas/HoldDepositAddressFrozen' depositAddressInactive: '#/components/schemas/HoldDepositAddressInactive' description: >- Why an `awaitingAction` transaction is held, and the deadline to resolve. Discriminated by `type`; each arm carries the fields that apply. omsxProjectId: type: string pattern: ^prj_.+$ description: >- Opaque OMS project ID (`prj_` prefix), e.g. `prj_01kpxxa7esk9a`. Nothing beyond the prefix is constrained — treat the whole value as an opaque string rather than parsing the suffix. x-go-type: string WalletCryptoInstrument: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - walletCrypto description: Type discriminator. category: type: string enum: - crypto description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- OMS wallet ID (`wlt_` prefix). Dereference via `GET /wallets/{id}`. Null while a deposit is still in flight and the wallet it lands in has not resolved yet. asset: type: string description: Canonical asset identifier. network: type: string description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. description: >- OMS-custodied crypto wallet instrument — a uniform reference. Dereference `GET /wallets/{id}` for the wallet record (on-chain address, custody type, balances). title: OMS wallet WalletExternalInstrument: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - walletExternal description: Type discriminator. category: type: string enum: - crypto description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: External Account ID (`ext_` prefix). Null when externalUnregistered. asset: type: string description: Canonical asset identifier. network: type: string description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: blockchainAddress: type: string description: On-chain address for this side. required: - blockchainAddress nullable: true description: >- `details.blockchainAddress` carries the address when the rendering projection exposes it, whether or not `id` is set. It is always null on `VirtualAccount.destination` and `DepositAddressWalletExternalDestination`; those projections render the registered external-account `id` without projecting its address. description: >- Externally-custodied crypto wallet instrument — a uniform reference. When registered, dereference the external account by `id` for any other details. `details.blockchainAddress` carries the address when the rendering projection exposes it, whether or not `id` is set. It is always null on `VirtualAccount.destination` and `DepositAddressWalletExternalDestination`; those projections render the registered external-account `id` without projecting its address. title: External wallet WalletFiatInstrument: type: object required: - type - category - id - asset - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - walletFiat description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string nullable: true pattern: >- ^(wlt_fiat_|[a-z]+_)([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ description: >- OMS fiat wallet ID (`wlt_` prefix — the same canonical form a crypto wallet renders; a legacy `wlt_fiat_` id is still accepted on input). Dereference via `GET /wallets/{id}`. Null on a book-transfer destination until the outbound leg is created: a deposit auto-forwarded to a fiat wallet can still be re-pointed until then, so there is no wallet to dereference yet. asset: type: string enum: - usd description: Fiat currency of the balance. Only `usd` today. network: type: string enum: - bookTransfer description: >- `bookTransfer` when this walletFiat is the destination of a Virtual Account / Deposit Address book-transfer credit — an internal ledger movement at the partner bank, no external rail. Absent when the walletFiat is a funding source. displayName: type: string description: >- Render-only summary for list/detail display. Always the same string the Wallet resource carries in its own `displayName` (today `USD balance ()`), so a side referencing a wallet and `GET /wallets/{id}` read back for it agree. Treat the format as opaque; it may change without a version bump. description: >- A fiat balance wallet OMS holds for the customer at a partner bank (e.g. USD at "Erebor Bank, N.A."). An internal ledger balance, always OMS-held: this arm carries no `details` and has no unregistered-sender case, unlike the other fiat arms. Dereference `GET /wallets/{id}` for the wallet record (provider, balance). title: Fiat wallet BankUsInstrument: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. On an inbound bank source it is the sending bank's own reference, echoed verbatim; on an outbound bank destination it is an echo of the `memo` you supplied. Absent when the sender supplied none, when the receiving institution does not relay the sender's reference, or when you set none. A message OMS composes for the rail itself is never surfaced here, so this can be absent even when a message travelled. type: type: string enum: - bankUs description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- External Account ID (`ext_` prefix). Null when externalUnregistered (e.g. an incoming wire from an unregistered sender). asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - ach - achSameDay - wire - rtp nullable: true description: >- Rail the funds move on. `rtp` is selectable on a Quote or a Deposit Address destination but not on a Virtual Account destination; every surface shares this response enum, so a record that already carries `rtp` is echoed wherever it appears — do not read `network == "rtp"` as proof of where the destination came from. Null when the underlying record carries a rail outside this set. secCode: allOf: - $ref: '#/components/schemas/SecCode' description: >- ACH SEC code (populated only on ach/achSameDay). Server-derived from the destination owner's and the source customer's entityType, read directly from the DB/Customer record — not from this wire-facing instrument. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: accountNumberLast4: type: string description: Last four digits of the account number. bankName: type: string nullable: true description: Bank display name. required: - accountNumberLast4 - bankName nullable: true description: >- Populated only when `id` is null (unregistered external sender); null for registered instruments. description: >- US bank account instrument — a uniform reference. Dereference the external account by `id` for routing number, account type, and full account number. title: US bank account BankIbanInstrument: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. On an inbound bank source it is the sending bank's own reference, echoed verbatim; on an outbound bank destination it is an echo of the `memo` you supplied. Absent when the sender supplied none, when the receiving institution does not relay the sender's reference, or when you set none. A message OMS composes for the rail itself is never surfaced here, so this can be absent even when a message travelled. type: type: string enum: - bankIban description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: External Account ID (`ext_` prefix). Null when externalUnregistered. asset: type: string description: Canonical asset identifier. network: type: string enum: - swift description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: accountNumberLast4: type: string description: Last four characters of the IBAN. bankName: type: string nullable: true description: Bank display name. required: - accountNumberLast4 - bankName nullable: true description: >- Populated only when `id` is null (unregistered external sender); null for registered instruments. `accountNumberLast4` carries the last 4 of the IBAN — no separate `ibanLast4` key on this slim shape. description: >- IBAN bank account instrument — a uniform reference. Dereference the external account by `id` for the BIC and bank address. title: IBAN bank account BankCanadaInstrument: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this rail — an echo of the `memo` you supplied on the request. Absent when you set none, in which case the payout carried the memo OMS generates; a message OMS composes for the rail itself is never surfaced here, so this can be absent even when a message travelled. type: type: string enum: - bankCanada description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: External Account ID (`ext_` prefix). Null when externalUnregistered. asset: type: string enum: - usd - cad description: Canonical asset identifier. network: type: string enum: - swift - local description: USD uses `swift`; CAD uses `local`. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: accountNumberLast4: type: string description: Last four digits of the account number. bankName: type: string nullable: true description: Bank display name. required: - accountNumberLast4 - bankName nullable: true description: >- Populated only when `id` is null (unregistered external sender); null for registered instruments. description: >- Canadian bank account instrument — a uniform reference. USD routes over SWIFT, CAD over local rails. Dereference the external account by `id` for institution/transit coordinates. title: Canadian bank account CardInstrument: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - card description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- Card ExternalAccount ID (`ext_` prefix). Null when no card external account is linked to the transaction. asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - card description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. description: >- Card instrument — a uniform reference. Usually registered: dereference the external account by `id` for the card brand, last 4, and expiry. title: Card CashInstrument: type: object required: - type - category - asset - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - cash description: Type discriminator. category: type: string enum: - cash description: 'High-level grouping: always `cash` for cash pickups and drops.' asset: type: string description: Canonical asset identifier. cashLocationId: type: string description: Cash location ID from `GET /cash-locations`. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. description: >- Cash pickup/drop instrument — a uniform reference. Dereference the cash location by `cashLocationId` for its address. title: Cash WalletCryptoDestination: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - walletCrypto description: Type discriminator. category: type: string enum: - crypto description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- OMS wallet ID (`wlt_` prefix). Dereference via `GET /wallets/{id}`. Null while a deposit is still in flight and the wallet it lands in has not resolved yet. asset: type: string description: Canonical asset identifier. network: type: string description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: OMS wallet WalletExternalDestination: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - walletExternal description: Type discriminator. category: type: string enum: - crypto description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: External Account ID (`ext_` prefix). Null when externalUnregistered. asset: type: string description: Canonical asset identifier. network: type: string description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: blockchainAddress: type: string description: On-chain address for this side. required: - blockchainAddress nullable: true description: >- `details.blockchainAddress` carries the address when the rendering projection exposes it, whether or not `id` is set. It is always null on `VirtualAccount.destination` and `DepositAddressWalletExternalDestination`; those projections render the registered external-account `id` without projecting its address. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: External wallet WalletFiatDestination: type: object required: - type - category - id - asset - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - walletFiat description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string nullable: true pattern: >- ^(wlt_fiat_|[a-z]+_)([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ description: >- OMS fiat wallet ID (`wlt_` prefix — the same canonical form a crypto wallet renders; a legacy `wlt_fiat_` id is still accepted on input). Dereference via `GET /wallets/{id}`. Null on a book-transfer destination until the outbound leg is created: a deposit auto-forwarded to a fiat wallet can still be re-pointed until then, so there is no wallet to dereference yet. asset: type: string enum: - usd description: Fiat currency of the balance. Only `usd` today. network: type: string enum: - bookTransfer description: >- `bookTransfer` when this walletFiat is the destination of a Virtual Account / Deposit Address book-transfer credit — an internal ledger movement at the partner bank, no external rail. Absent when the walletFiat is a funding source. displayName: type: string description: >- Render-only summary for list/detail display. Always the same string the Wallet resource carries in its own `displayName` (today `USD balance ()`), so a side referencing a wallet and `GET /wallets/{id}` read back for it agree. Treat the format as opaque; it may change without a version bump. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. description: >- The deposited value held as a fiat balance in the customer's fiat wallet (only `usd` today). Credited by an internal book transfer at the partner bank, so the resolved instrument reads `network: bookTransfer`. Selectable as a Deposit Address or Virtual Account destination; a Quote destination cannot be `walletFiat`. The wallet must belong to the route's customer (422 `WalletCustomerMismatch`) and be `active` (422 `WalletNotActive`). title: Fiat wallet BankUsDestination: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. On an inbound bank source it is the sending bank's own reference, echoed verbatim; on an outbound bank destination it is an echo of the `memo` you supplied. Absent when the sender supplied none, when the receiving institution does not relay the sender's reference, or when you set none. A message OMS composes for the rail itself is never surfaced here, so this can be absent even when a message travelled. type: type: string enum: - bankUs description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- External Account ID (`ext_` prefix). Null when externalUnregistered (e.g. an incoming wire from an unregistered sender). asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - ach - achSameDay - wire - rtp nullable: true description: >- Rail the funds move on. `rtp` is selectable on a Quote or a Deposit Address destination but not on a Virtual Account destination; every surface shares this response enum, so a record that already carries `rtp` is echoed wherever it appears — do not read `network == "rtp"` as proof of where the destination came from. Null when the underlying record carries a rail outside this set. secCode: allOf: - $ref: '#/components/schemas/SecCode' description: >- ACH SEC code (populated only on ach/achSameDay). Server-derived from the destination owner's and the source customer's entityType, read directly from the DB/Customer record — not from this wire-facing instrument. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: accountNumberLast4: type: string description: Last four digits of the account number. bankName: type: string nullable: true description: Bank display name. required: - accountNumberLast4 - bankName nullable: true description: >- Populated only when `id` is null (unregistered external sender); null for registered instruments. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: US bank account BankIbanDestination: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. On an inbound bank source it is the sending bank's own reference, echoed verbatim; on an outbound bank destination it is an echo of the `memo` you supplied. Absent when the sender supplied none, when the receiving institution does not relay the sender's reference, or when you set none. A message OMS composes for the rail itself is never surfaced here, so this can be absent even when a message travelled. type: type: string enum: - bankIban description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: External Account ID (`ext_` prefix). Null when externalUnregistered. asset: type: string description: Canonical asset identifier. network: type: string enum: - swift description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: accountNumberLast4: type: string description: Last four characters of the IBAN. bankName: type: string nullable: true description: Bank display name. required: - accountNumberLast4 - bankName nullable: true description: >- Populated only when `id` is null (unregistered external sender); null for registered instruments. `accountNumberLast4` carries the last 4 of the IBAN — no separate `ibanLast4` key on this slim shape. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: IBAN bank account BankCanadaDestination: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this rail — an echo of the `memo` you supplied on the request. Absent when you set none, in which case the payout carried the memo OMS generates; a message OMS composes for the rail itself is never surfaced here, so this can be absent even when a message travelled. type: type: string enum: - bankCanada description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: External Account ID (`ext_` prefix). Null when externalUnregistered. asset: type: string enum: - usd - cad description: Canonical asset identifier. network: type: string enum: - swift - local description: USD uses `swift`; CAD uses `local`. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. details: type: object properties: accountNumberLast4: type: string description: Last four digits of the account number. bankName: type: string nullable: true description: Bank display name. required: - accountNumberLast4 - bankName nullable: true description: >- Populated only when `id` is null (unregistered external sender); null for registered instruments. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: Canadian bank account CardDestination: type: object required: - type - category - id - asset - network - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - card description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- Card ExternalAccount ID (`ext_` prefix). Null when no card external account is linked to the transaction. asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - card description: Network identifier. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: Card CashDestination: type: object required: - type - category - asset - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. memo: type: string description: >- Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (`bankUs`, `bankIban`, `bankCanada`). type: type: string enum: - cash description: Type discriminator. category: type: string enum: - cash description: 'High-level grouping: always `cash` for cash pickups and drops.' asset: type: string description: Canonical asset identifier. cashLocationId: type: string description: Cash location ID from `GET /cash-locations`. displayName: type: string description: >- Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN. payoutOrigin: $ref: '#/components/schemas/PayoutOrigin' pickupCode: type: string description: >- Retail pickup code for a cash payout. Populated only on cash-out (pickup) destinations. companyDiscretionaryData: type: string description: >- Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied. title: Cash PricingSide: type: object properties: asset: type: string description: >- Currency these amounts are in. Same as the side's instrument asset, repeated here so pricing is self-contained. amountGross: type: string description: Amount on this side before fees are applied. amountNet: type: string description: >- Amount after fees: what is actually pulled from a source, or delivered to a destination. Identity: amountNet = amountGross − Σ fees(side) (this side's entries in `Pricing.fees`). description: >- Per-side economics for the `pricing` object: the side carries identity and amounts. Fees are not nested here; see `Pricing.fees`. PricingFee: type: object required: - type - side - asset - amount properties: type: type: string description: >- Fee kind. OPEN — clients must tolerate an unrecognised type. Known values today: "developer" (always `0` in alpha), "oms", "gas". side: type: string enum: - source - destination description: Which side this fee was deducted from. asset: type: string description: Currency this fee is denominated in — that side's asset. amount: type: string description: Fee amount, in `asset`. description: >- A single fee deducted on one side of a transaction/quote. Replaces the old nested `source.feesDeducted`/`destination.feesDeducted` objects with one flat, additive array: a new fee type is a new entry, never a schema change. ManualRecovery: type: object properties: type: type: string enum: - manualRecovery custodian: $ref: '#/components/schemas/DestinationCustodian' instructions: type: string referenceFields: $ref: '#/components/schemas/RecoveryReferenceFields' description: v0.11 manual-recovery detail (renamed from Recovery/operatorRecovery). HoldInformationRequested: type: object required: - required - type - instructions - requestedFrom properties: required: type: boolean description: Whether the hold is still blocking; false once resolved. since: type: string format: date-time description: When the hold started. deadline: type: string format: date-time description: Deadline to resolve before timeout. resolvedAt: type: string format: date-time nullable: true description: When the hold was resolved. Absent while the hold is outstanding. type: type: string enum: - informationRequested description: Type discriminator. instructions: type: string description: >- Human-readable statement of what is needed, safe to surface to the developer. Free text — do not parse it. requestedFrom: type: string description: >- Who the information is needed from. Today either `customer` (the end user, reached through you) or `developer` (you, the integrator). Open vocabulary — tolerate a value you do not recognise. customerId: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- The customer the request concerns (`cst_` prefix), when it is about a specific customer. Absent otherwise. description: >- Additional information is needed before the transaction can continue — typically a compliance or source-of-funds follow-up. Pairs with sub-status `awaitingAction.informationRequested`. `instructions` says what is being asked and `requestedFrom` says who must supply it. There is no API endpoint to satisfy the request. title: Information requested HoldSenderAttribution: type: object required: - required - type properties: required: type: boolean description: Whether the hold is still blocking; false once resolved. since: type: string format: date-time description: When the hold started. deadline: type: string format: date-time description: Deadline to resolve before timeout. resolvedAt: type: string format: date-time nullable: true description: When the hold was resolved. Absent while the hold is outstanding. type: type: string enum: - senderAttribution description: Type discriminator. matchableExternalAccountCriteria: allOf: - $ref: '#/components/schemas/MatchableExternalAccountCriteria' description: Registering a matching walletExternal EA releases this hold. description: DA received crypto from an address not linked to a counterparty. title: Sender attribution HoldDepositAddressFrozen: type: object required: - required - type properties: required: type: boolean description: Whether the hold is still blocking; false once resolved. since: type: string format: date-time description: When the hold started. deadline: type: string format: date-time description: Deadline to resolve before timeout. resolvedAt: type: string format: date-time nullable: true description: When the hold was resolved. Absent while the hold is outstanding. type: type: string enum: - depositAddressFrozen description: Type discriminator. description: The parent deposit address is in a compliance freeze. title: Deposit address frozen HoldDepositAddressInactive: type: object required: - required - type properties: required: type: boolean description: Whether the hold is still blocking; false once resolved. since: type: string format: date-time description: When the hold started. deadline: type: string format: date-time description: Deadline to resolve before timeout. resolvedAt: type: string format: date-time nullable: true description: When the hold was resolved. Absent while the hold is outstanding. type: type: string enum: - depositAddressInactive description: Type discriminator. cause: $ref: '#/components/schemas/HoldInactiveCause' description: The destination external account went deleted/invalid. title: Deposit address inactive Party: type: object required: - relationship - id - name properties: relationship: type: string enum: - customer - otherCustomer - externalRegistered - externalUnregistered description: Which kind of party this is. id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true description: >- `cst_` for customer/otherCustomer; `ctp_` for externalRegistered; null for externalUnregistered. name: type: string nullable: true description: >- Display name. Null only when genuinely unknown (an unattributed external sender). description: >- Response-only identity of who is on one side of a transaction — a uniform `{relationship, id, name}` reference. `id` is the Customer (`cst_`) for `customer`/`otherCustomer`, the Counterparty (`ctp_`) for `externalRegistered`, and null for `externalUnregistered`. Entity type and address live on the dereferenced Customer/Counterparty resource, not here. `name` is populated for every relationship except a genuinely-unknown external sender. SecCode: type: string enum: - ccd - ppd - web description: >- ACH SEC code. Populated only when the destination bank network is `ach`/`achSameDay`; null otherwise. Server-derived from the destination owner's and the source customer's `entityType`. PayoutOrigin: type: object required: - type - id - accountHolder - accountHolderName properties: type: type: string enum: - bank - blockchain id: type: string allOf: - $ref: '#/components/schemas/typeId' nullable: true accountHolder: allOf: - $ref: '#/components/schemas/PayoutOriginAccountHolder' nullable: true description: >- Whose legal identity the payment is sent under. Determined by OMS from the route's configuration — not a request field. Always present; null when OMS cannot determine it, and on destinations that have no sending legal identity (cash payouts, and crypto payouts outside a Deposit Address). A bank payout that goes out under the payment provider or the partner records that holder just before it is sent to the provider, and reports it only while a payout was or may have been created there; a send interrupted after the holder was recorded and before it went out has an unknown outcome and may report it. A failed send known to have created no payout at the provider, and a payout sent before holders were recorded (there is no backfill), report the fallback value instead, which may differ from the holder actually used. The fallback value, also reported before a holder is recorded and for payouts that always go out under the customer's own name, is the Deposit Address's value for the destination type the transaction pays (see `DepositAddressPayoutOrigin`) on a transaction created from a Deposit Address, and the value its route implies on any other. accountHolderName: type: string nullable: true description: >- The legal name the payment is sent under, resolved from `accountHolder` — the customer's own legal name for `customer`, the owning customer's legal name for `partner` (for now; a partner-level name may replace it later), or the payment provider's name for `paymentProvider`, which differs between a `bank` origin ("Coinme Inc FBO its Customers") and a `blockchain` origin. This is what the recipient sees as the sender. Like `accountHolder` and unlike `id`, it is populated as soon as it is determinable, so it appears on Quote and Deposit Address responses as well as Transactions. Null whenever `accountHolder` is null, and null on event payloads for `customer` and `partner`. description: >- Where last-mile delivery is sent *from*, as a uniform `{type, id}` reference — response-only. `id` is the Virtual Account (`va_`) or OMS wallet (`wlt_`) funding the leg; null before execution (Quote / Deposit Address echo the choice only) or when the origin has no partner-visible resource. Rail identifiers for the last-mile transfer live in the top-level `tracking` array with `leg: destination` — not here. DestinationCustodian: type: string enum: - ANCHORAGE_SG - ANCHORAGE_US - AQUANOW_CA - B2C2_UK - B2C2_US - BITGO_SG - BITGO_US - BITSTAMP_US - BVNK_US - CIRCLE_FR - CIRCLE_US - CITIBANK_US - COINBASE_US - COINSMART_CA - COPPER_CH - COPPER_UK - CUMBERLAND_DRW_LLC_US - CUMBERLAND_SG - EREBOR_BANK_US - FALCONX_US - FIDELITY_UK - FIDELITY_US - FIREBLOCKS_APAC - FIREBLOCKS_US - GALAXY_KY - GEMINI_US - KRAKEN_BVI - KRAKEN_EU_IE - KRAKEN_UK - KRAKEN_US - NUBANK_BR - PAXOS_US - RAMP_NETWORK_US - ROBINHOOD_US - WINTERMUTE_GB - SELF_HOSTED - OTHER RecoveryReferenceFields: type: object properties: transactionId: allOf: - $ref: '#/components/schemas/typeId' description: Transaction ID (`txn_` prefix). sourceTxHash: type: string description: Transaction hash of the originating inbound transfer. description: Reference identifiers for an operator-driven recovery. MatchableExternalAccountCriteria: type: object properties: type: type: string enum: - walletExternal description: Always `walletExternal` — the EA type that resolves the hold. blockchainAddress: type: string description: On-chain address. networkFamily: allOf: - $ref: '#/components/schemas/NetworkFamily' description: Network family of the sender's address. description: >- The wallet criteria a held inbound matches against to release: registering a walletExternal external account with this (customer, address, networkFamily) clears the sender-attribution hold. HoldInactiveCause: type: object properties: type: type: string enum: - destinationExternalAccount description: Always `destinationExternalAccount`. externalAccountId: allOf: - $ref: '#/components/schemas/typeId' description: External Account ID (`ext_` prefix). externalAccountStatus: $ref: '#/components/schemas/ExternalAccountStatusReason' invalidReason: allOf: - $ref: '#/components/schemas/ExternalAccountInvalidReason' description: >- Mirrors the destination ExternalAccount's `invalidReason` when `invalid`; absent when `deleted`. Typed to the closed enum per the OMS v0.13-3 contract (upstream points this at the ExternalAccountInvalidReason schema). description: >- Why a depositAddressInactive hold's destination external account went unusable. PayoutOriginAccountHolder: type: string enum: - customer - paymentProvider - partner description: >- Whose legal name an outbound payment is sent under — the name that appears on the recipient's statement. Determined by which institution executes the payout and by your project's configuration, not by anything you send: outbound fiat executed by Erebor Bank, N.A. goes out under the customer's own legal name (`customer`), while outbound fiat executed by Cross River Bank goes out under the payment provider (`paymentProvider`, `accountHolderName` "Coinme Inc FBO its Customers") or, on a project configured to send under its own name, under the partner (`partner`). A Deposit Address created while its customer holds an active Virtual Account from the same provider reports `customer` and names that Virtual Account in `payoutOrigin.id`; payouts are not yet sent from that account, so each of its transactions reports the holder described on `PayoutOrigin.accountHolder`. Crypto sent from a Deposit Address goes out under whoever holds the sending wallet. Read the pair rather than inferring either from a resource's `provider` field, which names the custodian of the account and can be a different company entirely. On a Virtual Account the pair is reported as a top-level `payoutOrigin`, present for its bank and crypto-wallet destinations and absent for `walletFiat`. Null on cash payouts and on crypto payouts outside a Deposit Address. New values may be added. NetworkFamily: type: string enum: - evm - solana - tron description: >- Crypto network family for a registered external wallet. A walletExternal is registered per family (an EVM address is valid across every EVM chain), and the registration covers every served network in that family. A create for a family the provider that provisions this project's walletExternal accounts does not serve is refused before anything is written, with 422 `NetworkFamilyNotServed`; depending on the provider, the refusal can be 403 `VendorConfigMissing` instead. ExternalAccountStatusReason: type: string enum: - deleted - invalid ExternalAccountInvalidReason: type: string enum: - accountClosed - accountFrozenByBank - routingOrAccountNumberInvalid - accountHolderDeceased - accountDoesNotSupportTransfers - payeeNameMismatch - walletUnreachableOnNetwork - billingAddressMismatch - cardExpired - cardClosedOrLostStolen - pushToCardUnsupported - cardDeclinedByIssuer description: >- Why an account that was previously usable no longer is. Present only when `status` is `invalid`; absent otherwise. The condition is account-level and permanent — another payout to this account fails the same way, so collect new details from the customer rather than retrying. Bank and wallet: `accountClosed`, `accountFrozenByBank`, `routingOrAccountNumberInvalid`, `accountHolderDeceased`, `accountDoesNotSupportTransfers` (the account type does not permit transfers — certain savings and escrow accounts, for example), `payeeNameMismatch`, `walletUnreachableOnNetwork`. Card: `billingAddressMismatch` (AVS failure), `cardExpired`, `cardClosedOrLostStolen`, `pushToCardUnsupported`, `cardDeclinedByIssuer`. For US bank accounts these are derived from the ACH return on a failed payout, with the raw code in `invalidReasonCode`: R02 → `accountClosed`; R03, R04 and R13 → `routingOrAccountNumberInvalid` (different codes, same remedy — get the correct numbers); R15 → `accountHolderDeceased`; R20 → `accountDoesNotSupportTransfers`. A return that does not indicate an account-level problem leaves the account alone: R23, where the recipient refused that particular credit, keeps the account `active` and is reported on the transaction's `error` instead. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Token from POST /auth/token ````