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 a 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. A chain request counts the first order the address receives from that network in that currency within 24 hours of the request; while that window is open with nothing paid, a second request for the same account, network and currency is refused. Where Grid funds a chain deposit through a quote instead, the address is the quote's and the deposit carries the quote's expiresAt; a payment after it is not converted (see paidAfterExpiry). For ACH_PULL, sourceCurrency must be USD, and amount in USD cents and sourceExternalAccountId are required. The source must be the agent customer's own ACTIVE USD external account with a Plaid ACH validation recorded through POST /agents/{agentId}/external-accounts/{externalAccountId}/ach-validations. The destination must be the customer's USDB EMBEDDED_WALLET. Creating an ACH_PULL deposit moves no money and records no authorization; it returns the authorization text the customer must accept. Requires the RECEIVE_FUNDS permission.

sourceNetwork
enum<string>
required

Network from which the customer will send the deposit.

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

Currency or asset the customer will deposit. Must be USD for LIGHTNING or ACH_PULL; 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. For ACH_PULL, it must be the customer's USDB EMBEDDED_WALLET.

Example:

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

sourceExternalAccountId
string

Required for ACH_PULL: the agent customer's own ACTIVE USD external account with a Plaid ACH validation. Refused with 400 if sent with another network.

Example:

"ExternalAccount:019542f5-b3e7-1d02-0000-000000000003"

amount
integer<int64>

USD amount in cents. Required for LIGHTNING and ACH_PULL; no amount is required for chain networks. For LIGHTNING, this is the exact amount the user pays, with deposit fees deducted before the destination asset is credited. For ACH_PULL, this is the amount to debit.

Required range: x <= 9000000000000000
Example:

2000

Response

Deposit created successfully

A deposit that converts funds from an external network into an internal account belonging to the agent's customer. For networks other than ACH_PULL, a deposit reported FAILED or EXPIRED can still become COMPLETED when the funds arrive late; the platform then receives the INCOMING_PAYMENT webhook for the deposit's transaction again, now COMPLETED. For ACH_PULL, PENDING means the deposit was created and is waiting for the customer's debit authorization; nothing has moved. It becomes EXPIRED at expiresAt, 30 minutes after creation. PROCESSING means the debit was submitted to the bank and the amount was credited to the destination USDB account. COMPLETED means the debit settled. FAILED means Grid refused the debit at submission or the bank returned it (see achPull.returnCode). A return after crediting does not remove the USDB credit, unlike platform ACH pulls, whose returns take the funds back.

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,
AVALANCHE,
ARBITRUM,
OPTIMISM,
TRON,
ACH_PULL
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, chain address or external account ID.

Available options:
LIGHTNING_INVOICE,
CHAIN_ADDRESS,
EXTERNAL_ACCOUNT
target
string
required

BOLT11 invoice when targetType is LIGHTNING_INVOICE; a chain address when CHAIN_ADDRESS; the source external account ID when EXTERNAL_ACCOUNT for ACH_PULL.

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.

quoteId
string

The quote that funds the deposit. The transaction that pays the deposit carries the same quoteId, so a payment can be matched to its deposit.

Example:

"Quote:019542f5-b3e7-1d02-0000-000000000006"

achPull
object

ACH debit details. Present only for ACH_PULL.

Payment links present only for a LIGHTNING deposit.

expiresAt
string<date-time> | null

When the deposit must be paid by: the invoice's expiry for LIGHTNING, or the quote's for a chain deposit Grid funds through a quote. Omitted or null for standing chain deposit addresses, which do not expire. For ACH_PULL, the authorization deadline, 30 minutes after creation.

Example:

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

paidAfterExpiry
boolean

Whether a payment for this deposit arrived after expiresAt, so only a deposit with an expiresAt can have one. A chain payment that arrives after its quote expired is not converted: the deposit stays EXPIRED and Lightspark is alerted to recover the funds by hand, so the payment must not be sent again. Absent or false while no late payment is known.

Example:

false