Deposit-Funded Orders

Overview

A deposit-funded order is an order you create without naming a source. Instead of pointing at a resource that already holds the funds, you tell Conduit which crypto asset the order will be funded in, and Conduit returns a crypto address to send that asset to. When the funds arrive and clear, the order executes on its own. Use it when the money is not with Conduit yet — the end customer is about to send crypto in, and you want one call that both locks the rate and tells you exactly where the funds should go. Use a named source instead when the customer already holds a balance in a wallet or Virtual Account. Deposit funding is crypto-only. An order funded from fiat always names its Virtual Account source explicitly.

Register the sending address first

A funding address accepts money only from addresses the customer has registered. Register the wallet the funds will be sent from before you create the order:

POST /v2/customers/{customerId}/wallets/registered-addresses
idempotency-key: <unique-key>

{
  "type": "self_custody",
  "chain": "ethereum",
  "address": "0x8f3a1e5b9c2d4a6f8e0b1c3d5f7a9b1c3d5e7f90",
  "selfCustodyAttestation": true
}

Registration is per customer, chain, and address: an address one customer registered does not clear funds for another. 201 means the address is registered and can send; 202 means screening is still running and it is not usable yet — poll until it reports registered. See Registered addresses. Anything arriving from an address that is not registered is sent straight back to where it came from. There is no grace period and no way to attach the sender afterwards — the check is simply whether the address was registered when the funds landed.

This makes deposit funding unavailable from wallets you cannot register — an exchange withdrawal, an OTC desk, an omnibus custodian. Fund those flows from a customer wallet or Virtual Account you name as the order’s source instead.

Creating one

Omit source and send sourceAsset — the asset code plus its chain. Exactly one of the two is required; sending both, or neither, is a 400.

POST /v2/orders
idempotency-key: <unique-key>

{
  "sourceAsset": { "code": "USDC", "chain": "ethereum" },
  "destination": { "type": "virtual_account", "id": "vac_..." },
  "lockSide": "source",
  "amount": "100.00"
}

Everything else is unchanged: destination, lockSide, amount, and an optional autoPayout behave exactly as they do on an order with a named source.

Do not send autoExecute. A deposit-funded order always executes automatically once its deposit clears — there is no other way to fund it — so sending the field at all (either value) is rejected with a 400 on /autoExecute. The order still reports autoExecute: true in its response.

The funding address

Every read of the order — the create response, GET /v2/orders, GET /v2/orders/:id, and the order.created webhook — carries a depositInstructions array. It is present only on deposit-funded orders, and it is always exactly one block:

{
  "id": "ord_...",
  "status": "pending",
  "depositInstructions": [
    {
      "type": "crypto_address",
      "address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd18",
      "chain": "ethereum",
      "asset": "USDC",
      "expiresAt": "2026-01-16T09:30:00.000Z"
    }
  ]
}

This is the same array-of-blocks shape a Virtual Account uses for depositInstructions, so funding instructions read the same way whatever you are funding. Send asset to address on chain before expiresAt. How much to send: the order’s totalDebit, not sourceAsset.amount. totalDebit is what the customer pays on the source side — the amount being converted plus any fee charged in the source asset — and the order executes only once the funds cover it. Read it off the same response that gave you the address.

Read the address off each order. Conduit owns the account behind it and may replace it at any time without notice, so an address cached against a customer can go stale. There is no endpoint that resolves a customer to their funding address — the order is the only place it is published.

`source` is absent, by design

A deposit-funded order omits source entirely from every response — POST /v2/orders, GET /v2/orders, and GET /v2/orders/:id alike. The account behind the funding address is Conduit infrastructure, not a customer resource: GET /v2/customers/:customerId/wallets does not list it, and GET /v2/customers/:customerId/wallets/:walletId returns 404 for it. There is no id to hand you, so none is sent. The presence of depositInstructions is the discriminator. Branch on that, not on source.

The funding deadline

lockExpiresAt on a deposit-funded order is a funding deadline, not a rate expiry, and depositInstructions[0].expiresAt always equals it.

The deadline is 5 minutes. It used to be 24 hours. Read lockExpiresAt off the order rather than assuming a window: a test that creates an order, does something else, then funds it will now find the order already cancelled (expired) and the funds on their way back.

If…	Then…
Funds covering `totalDebit` clear before the deadline	The order executes automatically and reaches `succeeded`.
Nothing arrives by the deadline	The order is cancelled: `order.cancelled` with `reason: "expired"`.
Less than `totalDebit` arrives	The order never reaches its total, so it expires like an unfunded one at the deadline.
More than `totalDebit` arrives	The order executes; the surplus is not credited (see below).

You can still cancel a pending deposit-funded order yourself with POST /v2/orders/:id/cancel.

Funds no order claims are sent back

Crypto that reaches a funding address without a matching order to claim it is not credited to the customer and cannot be spent. That covers every near miss: an amount that does not cover an order, funds arriving after the order expired or was cancelled, the surplus from an over-funded order, and funds sent to an address with no order behind it at all. Once no pending order is left on the address, Conduit sends those funds back on-chain to the address they came from. There is no separate waiting period: the order’s funding deadline is the only clock. A remainder worth under a dollar stays put rather than being sent back for less than it costs to move.

Reconcile against the order — its status, and depositInstructions — never against the deposit. If an order reached cancelled (expired), treat any funds sent to its address as on their way back to the sender.

Two consequences worth designing for:

A short send leaves the order pending, not part-filled. The order executes only once the address holds at least totalDebit; until then it sits pending and the clock keeps running. If the shortfall is never made up before the deadline, the order expires and the funds go back.
Re-funding needs a new order. Once an order is terminal its address no longer claims anything. Create a fresh order and read the new depositInstructions.

One case produces no return at all: funds whose on-chain sender Conduit could not determine have nowhere to go back to, so nothing is dispatched. Those stay on the funding address until Conduit resolves the sender and sends them back by hand.

Reading the deposit’s own record

A deposit into a funding address is an ordinary transaction, readable and listable on GET /v2/transactions exactly like any other deposit. When it has not failed, it carries three extra fields:

Field	Meaning
`funded`	The orders holding a claim on this transfer, oldest first, each as `{ orderId, orderStatus, amount }`. An order appears while it is `pending`, and stays for good once it has drawn the funds — including when it `failed` afterwards. An order that fails or is cancelled before it draws anything releases its claim and drops off the list.
`returned`	How much of this transfer has gone back to the sender.
`available`	How much of this transfer no order claims and nothing has sent back — still there to fund your next order.

A pending order’s entry in funded is earmarked for it; an order that has drawn the funds has actually moved them off the address, which can be well before it reports succeeded. That is why orderStatus rides on the field at all: an order that drew the funds and then failed keeps its entry and reports failed, because that money has left and does not come back. Only a claim that never drew anything is released when its order fails or is cancelled — that slice re-attributes to the next order or goes back. On a deposit that has not failed, the three fields always add up. source.assetAmount equals the sum of every funded[].amount plus returned plus available. The transfer is filled in the order the funds left it — returned first, then each claim in funded oldest first, and whatever is left is available — so no two of the three ever count the same money. Use this to answer “did my money stick?” without a second request. A failed deposit omits all three — see below for where to look instead.

{
  "id": "txn_dep1",
  "type": "deposit",
  "status": "completed",
  "source": {
    "type": "external_crypto",
    "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "1200.000000" }
  },
  "funded": [
    { "orderId": "ord_1", "orderStatus": "succeeded", "amount": { "code": "USDC", "chain": "ethereum", "amount": "1000.000000" } }
  ],
  "returned": { "code": "USDC", "chain": "ethereum", "amount": "200.000000" },
  "available": { "code": "USDC", "chain": "ethereum", "amount": "0.000000" }
}

An order carries the reverse view: fundedBy, an array of { transactionId, amount } naming every deposit that funded it. Read it off GET /v2/orders/:id.

The return is its own transaction

Money sent back from a funding address is a second transaction, type: "deposit_return", with its own id, status, and on-chain hash. It carries returnOf, the id of the deposit it returns:

{
  "id": "txn_ret1",
  "type": "deposit_return",
  "status": "completed",
  "source": {
    "type": "deposit_address",
    "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "200.000000" }
  },
  "destination": {
    "type": "external_crypto",
    "txHash": "0xOUTBOUND",
    "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "200.000000" }
  },
  "returnOf": "txn_dep1"
}

The deposit_return transaction itself always looks the same regardless of how much it returns. What it means for the deposit side varies:

A transfer that funded something first, then had a remainder returned — a partial return, or a full return of an over-funded transfer after its order settled — leaves the deposit completed, with returned and available reflecting exactly what happened.
A transfer that never funded anything — nothing ever claimed it, or it could not be accepted at all — leaves the deposit failed, with funded, returned and available all omitted. The deposit_return transaction is still there, and its returnOf still names the deposit: check it to see where the money went.

deposit_return carries no linkedOrderId: it is returned precisely because no order claimed it, and every order that did claim funds reports its own outcome on order.*.

When a funding transfer is not accepted

A transfer that is not accepted never funds anything, so the order cannot reach its total and expires at its deadline. The deposit itself ends in status: "failed" with a neutral reason and no failureCode — and, on a failed deposit, funded, returned and available are all omitted. Check GET /v2/transactions?type=deposit_return for the matching returnOf to see where the money went; no second transaction is produced when nothing was sent back. Contact support if it persists.

Filtering transactions at a funding address

GET /v2/transactions accepts sourceAddress — an exact match on the address that sent a transfer. To find every deposit that funded a given order, read fundedBy off that order instead (GET /v2/orders/:id).

The funding address on transactions

When a client-visible transaction has the funding address on one of its sides, that side is a deposit_address block rather than the usual wallet block:

{
  "type": "deposit_address",
  "address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd18",
  "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "100.000000" }
}

It carries no walletId — there is no wallet resource to look up. Treat it as its own case in your side handling; the chain travels with the asset inside assetAmount.

Errors

Code	Cause
`UNSUPPORTED_ASSET`	That asset and chain cannot fund an order this way. Name a `source` explicitly instead.
`VALIDATION_ERROR` on `/source`	Both `source` and `sourceAsset` were sent, or neither was.
`VALIDATION_ERROR` on `/sourceAsset`	`sourceAsset` named a fiat asset. Deposit funding is crypto-only.
`VALIDATION_ERROR` on `/autoExecute`	`autoExecute` was sent. Omit it.

Convert crypto

Wallet-to-wallet conversions, including the deposit-funded variant.

Money Movement Lifecycle

Where an order sits in the journey of a balance.

OFFRAMP orders in sandbox

Drive a deposit-funded order end to end with simulated funds.

Money

The amount shape every field on an order uses.

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Deposit-Funded Orders

Overview

Register the sending address first

Creating one

The funding address

`source` is absent, by design

The funding deadline

Funds no order claims are sent back

Reading the deposit’s own record

The return is its own transaction

When a funding transfer is not accepted

Filtering transactions at a funding address

The funding address on transactions

Errors

Convert crypto

Money Movement Lifecycle

OFFRAMP orders in sandbox

Money

​Overview

​Register the sending address first

​Creating one

​The funding address

​source is absent, by design

​The funding deadline

​Funds no order claims are sent back

​Reading the deposit’s own record

​The return is its own transaction

​When a funding transfer is not accepted

​Filtering transactions at a funding address

​The funding address on transactions

​Errors

​Related

Convert crypto

Money Movement Lifecycle

OFFRAMP orders in sandbox

Money

Overview

Register the sending address first

Creating one

The funding address

`source` is absent, by design

The funding deadline

Funds no order claims are sent back

Reading the deposit’s own record

The return is its own transaction

When a funding transfer is not accepted

Filtering transactions at a funding address

The funding address on transactions

Errors

Related