Create an agent deposit
Create a deposit for the authenticated agent’s customer. The returned target is a BOLT11 invoice for Lightning, an address for a supported chain or the source external account ID for ACH_PULL. Creating an ACH_PULL deposit moves no money and records no authorization; it returns the text the customer must accept before the platform calls authorizeAgentDepositDebit. Requires the RECEIVE_FUNDS permission in the agent’s policy.
Authorizations
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
Body
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.
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.
"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
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.
x <= 90000000000000002000
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.
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.
"2026-10-09T18:05:00Z"
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.
false