Skip to main content
POST
Create an agent deposit

Authorizations

Authorization
string
header
required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Headers

Idempotency-Key
string
required

Unique identifier used to return the same deposit for retries.

Maximum string length: 255
Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Request for an Orchestra-backed deposit into one of the agent customer's internal accounts. For LIGHTNING, set sourceCurrency to USD and provide amount; the user pays that exact USD amount and fees are deducted from the amount received. For chain networks, no amount is required and the returned standing deposit address does not expire.

sourceNetwork
enum<string>
required

Network from which the customer will send the deposit.

Available options:
LIGHTNING,
BASE,
ETHEREUM,
SOLANA,
POLYGON,
ARBITRUM,
TRON
sourceCurrency
string
required

Currency or asset the customer will deposit. Must be USD for LIGHTNING; for a chain network, use the asset sent on that chain. TRON supports USDT only.

Example:

"USD"

destinationInternalAccountId
string
required

Internal account that will receive the converted deposit. It must belong to the agent's associated customer and be allowed by the agent policy.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

amount
integer<int64>

Exact USD amount the user pays for a LIGHTNING deposit, in cents. Required for LIGHTNING; no amount is required for chain networks. This is an exact-in amount: deposit fees are deducted before the destination asset is credited.

Required range: x <= 9000000000000000
Example:

2000

Response

Deposit created successfully

An Orchestra-backed deposit that converts funds from an external network into an internal account belonging to the agent's customer.

id
string
required

System-generated unique deposit identifier.

Example:

"AgentDeposit:019542f5-b3e7-1d02-0000-000000000001"

status
enum<string>
required

Current processing state of the deposit.

Available options:
PENDING,
PROCESSING,
COMPLETED,
EXPIRED,
FAILED,
REFUNDED
sourceNetwork
enum<string>
required

Network from which the customer sends the deposit.

Available options:
LIGHTNING,
BASE,
ETHEREUM,
SOLANA,
POLYGON,
ARBITRUM,
TRON
sourceCurrency
string
required

Currency or asset the customer sends.

Example:

"BTC"

destinationInternalAccountId
string
required

Internal account that receives the converted deposit.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

destinationCurrency
string
required

Currency credited to the destination internal account.

Example:

"USDB"

targetType
enum<string>
required

Whether target is a Lightning invoice or chain address.

Available options:
LIGHTNING_INVOICE,
CHAIN_ADDRESS
target
string
required

BOLT11 invoice when targetType is LIGHTNING_INVOICE; otherwise the address on sourceNetwork to which the customer sends funds.

Example:

"lnbc1pndepositpp5..."

createdAt
string<date-time>
required

Time when the deposit was created.

Example:

"2026-10-09T18:00:00Z"

updatedAt
string<date-time>
required

Time when the deposit was last updated.

Example:

"2026-10-09T18:01:00Z"

sourceAmount
integer<int64>

Amount to send in the smallest unit of sourceCurrency, when the deposit quote fixes the source amount.

Example:

31500

estimatedReceiveAmount
object

Estimated amount credited to the destination internal account after fees, denominated in the destination asset. Present for LIGHTNING deposits.

Payment links for a LIGHTNING deposit. Absent for chain deposits.

depositMemo
string

Memo or tag that must accompany the deposit when the source network requires one.

Example:

"104923"

expiresAt
string<date-time> | null

Expiration time for a LIGHTNING invoice. Omitted or null for standing chain deposit addresses, which do not expire.

Example:

"2026-10-09T18:05:00Z"