Send from a wallet

Before you start: the OMS API is in early access. Every endpoint, including the ones in this guide, requires an early-access API key. Request access before you begin.Authenticate by exchanging your API key and secret for a bearer token at POST /auth/token, then send it as Authorization: Bearer {accessToken} on every request. Every mutating request (POST and PATCH) also requires an Idempotency-Key header. See Get started for the full flow.

This guide shows you how to move USDC out of an OMS custodial wallet using the two-step quote and transaction flow. The crypto-to-crypto path is described first; paying out to a bank account follows the same pattern and is covered at the end.

Send from a wallet flow

1App→OMSPOST /quotes (USDC/polygon → USDC/polygon)

2OMS→AppQuote with locked pricing

3App→OMSPOST /transactions {quoteId}

4OMS→PolygonPull USDC and send onchain

5OMS→AppWebhook: transaction.statusChanged

6OMS→AppWebhook: transaction.statusChanged

Prerequisites

Before sending USDC from a wallet, you need:

A customer with a cst_ ID.
A funded OMS wallet with a wlt_ ID containing enough USDC to cover the source amount plus gas (if not sponsoring gas).
A destination: another OMS wallet (its wlt_ ID) or an external onchain address (a 0x... address on the same network).
A webhook endpoint registered with POST /webhooks (or in the OMS Dashboard) to receive transaction events.

Step 1: Create a quote

Create a quote to lock in the pricing. OMS infers the direction as cryptoToCrypto from the source and destination instruments (an OMS wallet to a crypto address). Each side of a quote is a typed instrument: a type plus a details object. The quote source must be an OMS wallet (walletOms) or a card. The destination describes where the funds land. For a crypto payout, use a walletExternal instrument: either details.blockchainAddress for a raw address, or details.id for a registered external wallet (ext_wlt_...). Set amount on exactly one side; OMS calculates the other.

Request

POST /v0.11/quotes
Authorization: Bearer {accessToken}
Idempotency-Key: qt-alice-usdc-send-001
Content-Type: application/json

{
  "customerId": "cst_01H9Xa...",
  "source": {
    "type": "walletOms",
    "details": { "id": "wlt_01H9Xb...", "asset": "usdc", "network": "polygon" },
    "amount": "2000.00"
  },
  "destination": {
    "type": "walletExternal",
    "details": {
      "blockchainAddress": "0xAbC1230000000000000000000000000000DeF456",
      "asset": "usdc",
      "network": "polygon"
    }
  },
  "sponsorGas": true
}

Required fields:

customerId: The customer who owns this transaction.
source: A typed instrument. Set type to walletOms and put the OMS wallet id, asset (usdc or usdt), and network (polygon, ethereum, base) in details.
destination: A typed instrument naming where the funds land. For a crypto payout, use type: "walletExternal" with either details.blockchainAddress (a raw address) or details.id (a registered external wallet, ext_wlt_ prefix), plus asset and network.
amount on exactly one side: Here we set it on the source (send 2,000 USDC). OMS calculates the destination amount after fees. Set it on the destination instead to target an exact received amount.

Optional fields:

sponsorGas: When true, OMS absorbs gas fees. The customer sees source-side fees as zero and the actual gas cost appears in pricing.sponsorGasCost. At launch gas is always sponsored.
metadata: Up to 20 arbitrary key-value pairs.

Response, `201 Created`

{
  "id": "qt_01H9Xt...",
  "object": "quote",
  "status": "open",
  "sourceToDestination": "cryptoToCrypto",
  "customerId": "cst_01H9Xa...",
  "source": {
    "party": {
      "relationship": "customer",
      "customerId": "cst_01H9Xa...",
      "entityType": "individual"
    },
    "type": "walletOms",
    "category": "crypto",
    "details": {
      "id": "wlt_01H9Xb...",
      "asset": "usdc",
      "network": "polygon",
      "blockchainAddress": "0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1",
      "custodyType": "custodial",
      "txHash": null
    }
  },
  "destination": {
    "party": { "relationship": "externalUnregistered", "name": null, "address": null },
    "type": "walletExternal",
    "category": "crypto",
    "details": {
      "id": null,
      "asset": "usdc",
      "network": "polygon",
      "blockchainAddress": "0xAbC1230000000000000000000000000000DeF456"
    }
  },
  "pricing": {
    "source": {
      "asset": "usdc",
      "amountGross": "2000.00",
      "amountNet": "2000.00",
      "feesDeducted": { "total": "0.00", "developer": "0.00", "oms": "0.00", "gas": "0.00" }
    },
    "destination": {
      "asset": "usdc",
      "amountGross": "2000.00",
      "amountNet": "2000.00",
      "feesDeducted": { "total": "0.00", "developer": "0.00", "oms": "0.00", "gas": "0.00" }
    },
    "pair": "usdc/usdc",
    "exchangeRate": "1.0000",
    "effectiveRate": "1.0000",
    "fixedAmountSide": "source",
    "sponsorGas": true,
    "sponsorGasCost": "0.00"
  },
  "metadata": null,
  "expiresAt": "2026-01-15T10:05:00Z",
  "createdAt": "2026-01-15T10:00:00Z"
}

Key fields in the response:

id: The quote ID (prefix qt_). You pass it to create the transaction.
status: "open": Pricing is locked, awaiting acceptance.
sourceToDestination: "cryptoToCrypto": The direction OMS inferred from the instruments.
source.party and destination.party: Identify who is on each side. Here the source is your customer (relationship: "customer") and the destination is an unregistered external address (relationship: "externalUnregistered").
pricing: All money lives here. pricing.destination.amountNet is what the destination receives. At launch OMS absorbs fees and gas, so the feesDeducted components are "0.00" and pricing.sponsorGas is true.
pricing.sponsorGasCost: The estimated gas cost OMS absorbs. This is an out-of-band cost, not deducted from the destination amount.
expiresAt: Pricing expires after a short window. Create a new quote if it lapses.

If the customer accepts the pricing, proceed to Step 2. If the quote expires, create a new one.

Step 2: Create the transaction

Accept the quote by creating a transaction that references the quote ID. This is the point of no return: USDC is pulled from the wallet and the onchain send begins.

Request

POST /v0.11/transactions
Authorization: Bearer {accessToken}
Idempotency-Key: txn-alice-usdc-send-001
Content-Type: application/json

{
  "quoteId": "qt_01H9Xt..."
}

The request body is intentionally thin: the quote is the contract. All source, destination, and pricing details were locked in Step 1. The transaction ID prefix is txn_.

Response, `201 Created`

{
  "id": "txn_01H9Xd...",
  "object": "transaction",
  "sourceToDestination": "cryptoToCrypto",
  "status": "processing",
  "subStatus": "processing.fundsPulled",
  "customerId": "cst_01H9Xa...",
  "source": {
    "party": {
      "relationship": "customer",
      "customerId": "cst_01H9Xa...",
      "entityType": "individual"
    },
    "type": "walletOms",
    "category": "crypto",
    "details": {
      "id": "wlt_01H9Xb...",
      "asset": "usdc",
      "network": "polygon",
      "blockchainAddress": "0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1",
      "custodyType": "custodial",
      "txHash": "0x7f2a9b...c3d4e5"
    }
  },
  "destination": {
    "party": { "relationship": "externalUnregistered", "name": null, "address": null },
    "type": "walletExternal",
    "category": "crypto",
    "details": {
      "id": null,
      "asset": "usdc",
      "network": "polygon",
      "blockchainAddress": "0xAbC1230000000000000000000000000000DeF456"
    }
  },
  "pricing": {
    "source": {
      "asset": "usdc",
      "amountGross": "2000.00",
      "amountNet": "2000.00",
      "feesDeducted": { "total": "0.00", "developer": "0.00", "oms": "0.00", "gas": "0.00" }
    },
    "destination": {
      "asset": "usdc",
      "amountGross": "2000.00",
      "amountNet": "2000.00",
      "feesDeducted": { "total": "0.00", "developer": "0.00", "oms": "0.00", "gas": "0.00" }
    },
    "pair": "usdc/usdc",
    "exchangeRate": "1.0000",
    "effectiveRate": "1.0000",
    "fixedAmountSide": "source",
    "sponsorGas": true,
    "sponsorGasCost": "0.42"
  },
  "estimatedArrival": null,
  "error": null,
  "hold": null,
  "metadata": null,
  "createdAt": "2026-01-15T10:01:00Z",
  "updatedAt": "2026-01-15T10:01:00Z",
  "expiresAt": null
}

What to notice:

status: "processing": USDC has been pulled from the wallet and the onchain send is underway.
subStatus: "processing.fundsPulled": Optional operational detail in dot notation, indicating the USDC has been pulled. The next sub-status reflects send progress. Branch on status alone.
source.details.txHash: The onchain transaction hash for the send.
pricing.sponsorGasCost: "0.42": Final gas cost (may differ slightly from the quote estimate).
hold: null: No hold is in effect. If a transaction is blocked on the developer, an upstream provider, or compliance, status becomes awaitingAction and hold carries the detail.

Webhook: `transaction.statusChanged`

OMS fires transaction.statusChanged when the transaction enters processing, and again on every later transition. The full transaction arrives under the envelope’s data:

{
  "id": "whd_01H9Xz...",
  "eventId": "evt_01H9Xw...",
  "eventType": "transaction.statusChanged",
  "sequence": 1,
  "createdAt": "2026-01-15T10:01:02Z",
  "occurredAt": "2026-01-15T10:01:00Z",
  "data": {
    "id": "txn_01H9Xd...",
    "object": "transaction",
    "sourceToDestination": "cryptoToCrypto",
    "status": "processing",
    "subStatus": "processing.fundsPulled",
    "customerId": "cst_01H9Xa...",
    "source": { "type": "walletOms", "category": "crypto", "details": { "id": "wlt_01H9Xb...", "asset": "usdc", "network": "polygon", "txHash": "0x7f2a9b...c3d4e5" } },
    "destination": { "type": "walletExternal", "category": "crypto", "details": { "asset": "usdc", "network": "polygon", "blockchainAddress": "0xAbC1230000000000000000000000000000DeF456" } },
    "pricing": { "...": "full pricing object" },
    "error": null,
    "hold": null,
    "metadata": null,
    "createdAt": "2026-01-15T10:01:00Z",
    "updatedAt": "2026-01-15T10:01:00Z"
  }
}

One event covers every transition, so branch on data.status rather than on the event name. previousStatus is absent here because processing is the initial state; on later transitions it names the status the transaction left. Deduplicate on id, and use sequence to ignore a delivery older than one you already applied. See Webhook events for the delivery envelope and the full catalog.

Step 3: Track the transaction

OMS pulls the USDC, broadcasts the onchain send, and the funds arrive at the destination address once the transaction confirms. OMS fires transaction.statusChanged again when the transaction reaches completed:

{
  "id": "txn_01H9Xd...",
  "object": "transaction",
  "sourceToDestination": "cryptoToCrypto",
  "status": "completed",
  "subStatus": null,
  "customerId": "cst_01H9Xa...",
  "source": { "type": "walletOms", "category": "crypto", "details": { "id": "wlt_01H9Xb...", "asset": "usdc", "network": "polygon", "txHash": "0x7f2a9b...c3d4e5" } },
  "destination": { "type": "walletExternal", "category": "crypto", "details": { "asset": "usdc", "network": "polygon", "blockchainAddress": "0xAbC1230000000000000000000000000000DeF456" } },
  "pricing": { "...": "full pricing object" },
  "error": null,
  "hold": null,
  "metadata": null,
  "createdAt": "2026-01-15T10:01:00Z",
  "updatedAt": "2026-01-15T10:02:30Z"
}

What changed from the processing state:

status is now completed and subStatus is null.
updatedAt reflects when the onchain send confirmed.

At this point the flow is done. 2,000 USDC was pulled from the custodial wallet and delivered to the destination address. OMS absorbed the fees and the gas cost reported in pricing.sponsorGasCost.

Polling alternative

If you prefer polling over webhooks, retrieve the transaction directly:

GET /v0.11/transactions/txn_01H9Xd...
Authorization: Bearer {accessToken}

Poll until status is completed or failed. Webhooks are preferred for production: they avoid unnecessary requests and notify you the moment status changes.

Failure handling

If the transaction fails after USDC has been pulled (for example, an onchain error or a compliance block), status moves to failed and OMS fires transaction.statusChanged. The error object in data describes what went wrong:

{
  "id": "txn_01H9Xd...",
  "object": "transaction",
  "sourceToDestination": "cryptoToCrypto",
  "status": "failed",
  "subStatus": null,
  "error": {
    "code": "sendRejected",
    "message": "Onchain send could not be completed"
  }
}

failed is terminal. Inspect error.code to decide how to retry or surface the failure to the customer.

Returns and refunds

A bank payout that fails or is returned after the funds left the wallet (an invalid account, a bank rejection, a return code) does not strand the money. The transaction’s error object reports what happened and how the funds come back:

error.recoverable tells you whether the funds are being returned.
error.refund tracks the automatic return: the amount, asset, network, the destinationWallet receiving the re-credit, a status (pending, completed, failed), and the on-chain txHash once delivered. Because fiat payouts are funded from the wallet’s stablecoin balance, a failed payout re-credits the stablecoin side automatically; there is nothing to request.
error.recovery appears instead of refund in the rare case where funds sit unattributed upstream and an operator-driven recovery is required; it carries the reference identifiers and instructions for that process.

The refund progresses on the same transaction, and transaction.statusChanged fires on its transitions too: once as error.refund.status moves to completed, or to failed if the re-credit itself fails and needs operator follow-up. Read data.error.refund to tell the two apart, since the event name is identical to the one that reported the original failure. Watch for the refund on the same transaction object rather than creating a compensating transfer yourself: crediting your user when status turns failed and again when refund.status turns completed is the classic double-credit bug. These rails have no card-style chargeback exposure: OMS does not enable ACH pull, so an inbound deposit cannot be clawed back the way a card payment can.

Holds and compliance review

If a transaction is blocked on the developer, an upstream provider, or compliance, it moves to awaitingAction rather than failing. The event catalog has no dedicated hold event, so read the transaction to observe the state; the subStatus carries the operational detail, and the hold object is populated when a specific, typed hold applies:

GET /v0.11/transactions/txn_01H9Xd...
Authorization: Bearer {accessToken}

{
  "id": "txn_01H9Xd...",
  "object": "transaction",
  "sourceToDestination": "cryptoToFiatAccount",
  "status": "awaitingAction",
  "subStatus": "processing.underReview",
  "hold": null
}

When a typed hold applies, hold.type is one of senderAttribution, depositAddressFrozen, or depositAddressInactive, and the object carries the fields for that reason. awaitingAction is non-terminal. Once the hold clears, the transaction returns to processing and continues to completed or failed, firing the corresponding transaction event. Branch on status: a transaction in awaitingAction is not done.

Webhook events

Both flows in this guide, the crypto send and the bank payout, report through one event. Subscribe to it once and branch on the transaction’s status. See Webhook events for the envelope and the full catalog.

Event	When
`transaction.statusChanged`	The transaction changed status: executing, delivered, failed, or refunded
`transaction.cryptoToFiat.underReview`	A bank payout was held for compliance review. Subscribe explicitly; the `*` wildcard excludes it
`transaction.cryptoToCrypto.underReview`	A crypto send was held for compliance review. Subscribe explicitly; the `*` wildcard excludes it

Key points

The quote is the contract. The transaction request body is just { "quoteId": "..." }: no overrides.
Sides are typed instruments. A quote source is walletOms or card; the crypto destination is walletExternal, either with details.blockchainAddress for a raw address or details.id for a registered external wallet.
Money lives in pricing. The source and destination sides carry identity and instrument only. Read amounts, rates, and fees from the top-level pricing object.
OMS absorbs fees and gas at launch. feesDeducted components are "0.00" and pricing.sponsorGas is true. The gas cost OMS covers appears in pricing.sponsorGasCost, which may differ slightly between quote and transaction.
details.txHash is populated on the source because OMS executes an onchain transaction to send the USDC.
Idempotency keys are per request. Use a distinct Idempotency-Key for the quote and the transaction so retries are safe and don’t create duplicates.

Pay out to a bank account

A fiat payout follows the same two-step quote and transaction flow. The quote source is still an OMS wallet holding USDC. The difference is the destination: instead of a crypto instrument, you target an external bank account. OMS infers the direction as cryptoToFiatAccount. Register the bank account first with POST /external-accounts: pass an owner ({ "kind": "customer", "customerId": "..." }), type: "bankUs", and a bankUs object with the account and routing numbers. OMS returns the ext_bankUs_ ID; the account starts pending and flips to active when provisioning completes. Reference that ID in the quote’s destination, with asset: "usd", a fiat network (ach, achSameDay, wire, or rtp), and accountHolder: "customer" (the only accepted value). The payout requires the customer’s usd endorsement to be ACTIVE.

{
  "customerId": "cst_01H9Xa...",
  "source": {
    "type": "walletOms",
    "details": { "id": "wlt_01H9Xb...", "asset": "usdc", "network": "polygon" },
    "amount": "2000.00"
  },
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "ext_bankUs_01H9X...",
      "asset": "usd",
      "network": "ach",
      "accountHolder": "customer"
    }
  },
  "sponsorGas": true
}

Once the quote is open, create the transaction the same way, with { "quoteId": "..." }. Track it with the transaction.statusChanged event, or by polling GET /v0.11/transactions/{transactionId}. ACH transfers typically settle in 1 to 3 business days; wire and rtp are faster. The same operational notes apply: the quote is the contract, money lives in pricing, and you should use a distinct idempotency key per request. See Customer onboarding for the full external-account registration walkthrough.

For card rails, set settlementType on the quote to choose where the crypto lands: internal keeps it in OMS custody, external delivers it to an on-chain wallet. It defaults to external for a card buy and internal for a card sell, and is ignored for non-card rails.

Overview

Introduction

Fundamentals

Prerequisites

Step 1: Create a quote

Request

Response, `201 Created`

Step 2: Create the transaction

Request

Response, `201 Created`

Webhook: `transaction.statusChanged`

Step 3: Track the transaction

Polling alternative

Failure handling

Returns and refunds

Holds and compliance review

Webhook events

Key points

Pay out to a bank account

​Prerequisites

​Step 1: Create a quote

​Request

​Response, 201 Created

​Step 2: Create the transaction

​Request

​Response, 201 Created

​Webhook: transaction.statusChanged

​Step 3: Track the transaction

​Polling alternative

​Failure handling

​Returns and refunds

​Holds and compliance review

​Webhook events

​Key points

​Pay out to a bank account

Prerequisites

Step 1: Create a quote

Request

Response, `201 Created`

Step 2: Create the transaction

Request

Response, `201 Created`

Webhook: `transaction.statusChanged`

Step 3: Track the transaction

Polling alternative

Failure handling

Returns and refunds

Holds and compliance review

Webhook events

Key points

Pay out to a bank account