Standing Deposit Addresses

A standing deposit address is a permanent payment instruction. You choose a destination once. Orchestra returns deposit addresses on the enabled source chains, detects supported deposits, obtains a fresh quote, and creates an order automatically. You do not call /quote or /submit for each deposit. Use this flow when a customer should keep using the same deposit addresses and receive a variable amount of one destination asset. For an exact output amount or a price agreed before payment, use Quote and Submit.

What you create

One customer reference identifies one instruction within your partner account. The instruction contains a destination chain, asset and address, plus slippage and fee settings. Its source addresses may receive repeated deposits.

Record	Meaning
Customer reference (`ref`)	Your stable identifier for the instruction, such as `customer-123-usdc-v1`. Use it in all standing-address API paths.
Standing address ID	Orchestra’s identifier for the instruction. Store it alongside your reference.
Deposit	One observed funding event, identified by its deposit `id`.
Batch	The deposits reserved for one conversion or refund. Several deposits can share a `batchId`.
Order	The conversion created from a batch. Track it through the ordinary order API and webhooks.

The instruction is immutable. To change the destination, slippage, fees or configured refund addresses, create a new reference and distribute its new addresses. You can pause the old instruction, but you cannot redirect its addresses to the new destination.

Create an instruction

Make these calls from your backend using a secret server key (fn_...). Client keys (fnp_...) cannot access standing-address endpoints, including reads. Register an order webhook before accepting deposits. Choose a destination from Supported Routes. Standing-address availability is narrower than the full route catalog: the deployment and your partner’s admission determine which source chains can be issued. The create response is authoritative for the addresses you can display. Bitcoin availability is partner- and route-dependent. Set the environment variables below, replacing the recipient with an address you control on the destination chain. Persist the reference, request body and idempotency key before sending the request; reuse them if the request times out.

export BASE_URL='https://orchestration.flashnet.xyz'
export FLASHNET_API_KEY='<your-server-key>'
export STANDING_REF='customer-123-usdc-v1'
export CREATE_KEY='standing-create-customer-123-usdc-v1'
export RECIPIENT_ADDRESS='<your-Base-USDC-recipient>'

curl --fail-with-body --request PUT \
  "$BASE_URL/v1/standing-deposit-addresses/$STANDING_REF" \
  --header "Authorization: Bearer $FLASHNET_API_KEY" \
  --header "X-Idempotency-Key: $CREATE_KEY" \
  --header 'Content-Type: application/json' \
  --data "{
    \"destination\": {
      \"chain\": \"base\",
      \"asset\": \"USDC\",
      \"address\": \"$RECIPIENT_ADDRESS\"
    },
    \"slippageBps\": 50
  }"

A successful response is HTTP 200. This illustrative response contains two source chains; the keys and addresses in your response may differ:

{
  "standingAddressId": "sda_example",
  "addresses": {
    "base": "0x...",
    "solana": "..."
  },
  "enabled": true
}

Use the returned address for the user’s chosen source chain. An address returned for one EVM chain does not authorize deposits on another chain, even when the address string is identical. Keep chain labels visible beside addresses and QR codes. Publish addresses only after a successful response. A registration failure may leave an instruction stored while observation setup is incomplete. Retry the same instruction; do not invent an address or create a new reference to work around a temporary failure. Store the complete instruction in your application. GET returns the address map and enabled state, not the destination or fee settings. There is no endpoint to list all your standing instructions, so retain your customer-reference mapping. See the API reference for every request field, response field and error.

Accept deposits

The user sends a supported asset to the returned address on the matching chain. Sending funds is the only per-deposit action required from the user or your backend.

Do not send the destination asset on the destination chain. With the Base USDC destination above, a Base USDC deposit is held with standing_identity_pair; it is not forwarded to the recipient. Request an eligible refund for such a deposit.

Address issuance does not guarantee that every token or amount can convert. Check the current route catalog and amount guidance for the source asset and destination. Supported tokens, route availability and fees can change after an address is issued. An estimate can preview a conversion, but it does not lock the price of a future standing deposit. Orchestra verifies the transaction and its source, waits for the applicable confirmation policy, and prices the conversion when it prepares the batch. The final received amount depends on the deposit, the current price, network costs and fees. There is no fixed deposit-to-order latency guarantee.

Minimum amounts and dust

Source	Below-minimum behavior
EVM and Solana	A later eligible deposit can combine with earlier unreserved dust on the same address, chain and asset. Different assets and chains are never combined.
Bitcoin	Each transaction output is independent and must cover its own claim fee and route minimum. Later outputs do not make an earlier undersized output convertible.

A batch can therefore contain several EVM or Solana deposits but produces one order. Fees accrue when funds convert, not merely because dust is observed. For Bitcoin, two outputs to the same address in one transaction are separate deposits. Each eligible output produces its own batch and order. Store both sourceTxId and sourceTxIndex to identify the output. Standing Bitcoin deposits use confirmed-output processing; do not assume the liquidation-address ZeroConf flow applies.

Track deposits and orders

Use both deposit polling and ordinary order webhooks. Webhooks describe orders; a deposit that is waiting, below minimum or held before order creation may have no order event yet.

curl --fail-with-body \
  "$BASE_URL/v1/standing-deposit-addresses/$STANDING_REF/deposits?limit=50&offset=0" \
  --header "Authorization: Bearer $FLASHNET_API_KEY"

Persist each deposit by its id. When orderId becomes non-null, associate that order with the customer and track it using the order API and webhook events. Several deposit IDs can point to the same order; deduplicate order handling by orderId. The deposit response exposes both status and batchState. Once an order exists, status is the order’s status. batchState continues to describe the standing allocation. For example, an accepted refund request can show batchState: "refund_requested" while the order remains paused until the worker processes it. Neither an orderId nor a committed batch proves that the customer has been paid. Pages are newest-first and use offsets, not a snapshot cursor. Follow nextOffset until it is null, deduplicate by deposit ID, and periodically refresh recent pages so that existing rows receive status updates. New deposits can shift page boundaries during a scan. Do not implement reconciliation as a one-time walk that never revisits earlier rows. Verify webhook signatures, accept duplicate delivery, and reconcile against the API. The reference explains the deposit fields and states.

Pause and resume

Pause an instruction to stop new conversions while continuing to observe incoming deposits:

curl --fail-with-body --request PATCH \
  "$BASE_URL/v1/standing-deposit-addresses/$STANDING_REF" \
  --header "Authorization: Bearer $FLASHNET_API_KEY" \
  --header 'X-Idempotency-Key: standing-pause-customer-123-usdc-v1-1' \
  --header 'Content-Type: application/json' \
  --data '{"enabled":false}'

Resume with {"enabled":true} and a new idempotency key. Reuse a key only when retrying that exact action. Pausing does not block on-chain deposits, delete an address, cancel already committed source transactions or automatically refund funds. Remove the address from your deposit UI while paused. Work stopped specifically by the pause can retry after resume; other holds and requested refunds are not cleared by resuming.

Request a refund

Use POST /:ref/resolve to request return of eligible unconverted deposits or a held batch. Supply a refund address on the source chain that the customer can receive funds at. Never assume a deposit’s sender address is a valid return address, particularly for exchange withdrawals. For unreserved deposits, submit their deposit IDs. They must belong to the same source binding and asset. Bitcoin accepts exactly one output per request.

curl --fail-with-body --request POST \
  "$BASE_URL/v1/standing-deposit-addresses/$STANDING_REF/resolve" \
  --header "Authorization: Bearer $FLASHNET_API_KEY" \
  --header 'X-Idempotency-Key: standing-refund-deposit-1' \
  --header 'Content-Type: application/json' \
  --data '{
    "depositIds": ["<deposit-id>"],
    "refundAddress": "<customer-address-on-source-chain>"
  }'

For a held batch, use {"batchId":"<batch-id>","refundAddress":"<source-chain-address>"} instead. Do not send both selectors. HTTP 202 with status: "refund_requested" means the request was recorded. A worker still checks ownership, custody, screening and refund eligibility. It is not proof of a completed refund. Continue polling deposits and, when present, the order. Use refundTxId when available and check ordinary order details when an order exists. Funds already consumed by a conversion cannot be refunded again from later deposits. A screening hold or uncertain transaction outcome may require review even after a request is accepted. For Bitcoin, a direct unclaimed-output refund requires six confirmations and pays the actual refund output after transaction fees. The optional registration-time refundAddresses map supplies source-chain targets to generated orders. It does not automatically return all dust or held deposits and does not remove /resolve’s explicit refundAddress requirement.

Fees

slippageBps defaults to 50 (0.5%). feeBps defaults to 0 and sets a floor for the ordinary platform-fee policy applied to each batch; zero does not promise a free conversion. Network costs and any configured affiliate fees still apply. Standing instructions support registered affiliateIds, including per-instruction basis-point overrides. Their resolved configuration is frozen at registration. Updating the affiliate profile later does not change an existing instruction. Inline appFees are not accepted. See Affiliates to register profiles and the standing API fields for limits.

Handle common situations

Situation	Application behavior
Registration times out or returns a temporary error	Retry the same reference and instruction. Use `GET` to retrieve the current address map; never expose an inferred address.
`instruction_conflict`	Compare with the instruction you stored. Use a new reference for changed instructions.
An expected source chain is absent	Do not offer deposits on that chain. An address on another chain is not a substitute.
A confirmed deposit is absent from `/deposits`	Confirm the chain, asset and recipient on-chain; refresh after observation catches up. If it remains missing, retain the transaction hash and Bitcoin output index for investigation. Do not ask the customer to pay again.
`below_minimum`	Explain the source-specific dust behavior above, or request an eligible refund.
A row is `held` or has a non-null `code`	Read both `status` and `batchState`. Resume only a pause you intended to lift; request an eligible refund or surface the reason for review.
Refund returns `409 refund_not_available`	Refresh the deposits. They may already be reserved or spent, grouped incorrectly, or in a state that cannot accept a refund request.
`202 refund_requested` persists	Keep showing a pending return. Inspect updated deposit and order states; do not represent acceptance as payment.
You need to change the recipient	Create a new reference, switch the UI to its addresses, and pause the old instruction. Continue monitoring old addresses for late deposits.

For an unresolved issue, retain your customer reference, standing address ID, source chain and asset, transaction hash/output index, deposit IDs, batch/order IDs, status, batchState, code, timestamps and any refund transaction ID. These identify the exact funds and action without sharing your API key.

Overview

Concepts

Guides

Reference

Security

Standing Deposit Addresses

What you create

Create an instruction

Accept deposits

Minimum amounts and dust

Track deposits and orders

Pause and resume

Request a refund

Fees

Handle common situations

​What you create

​Create an instruction

​Accept deposits

​Minimum amounts and dust

​Track deposits and orders

​Pause and resume

​Request a refund

​Fees

​Handle common situations

What you create

Create an instruction

Accept deposits

Minimum amounts and dust

Track deposits and orders

Pause and resume

Request a refund

Fees

Handle common situations