Create an agent deposit

Create a deposit for the authenticated agent’s customer. The returned target is a BOLT11 invoice for Lightning or an address for a supported chain. Requires the RECEIVE_FUNDS permission in the agent’s policy.

POST /agents/me/deposits

Create an agent deposit

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/deposits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "sourceCurrency": "USD",
  "destinationInternalAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "amount": 2000
}
'

201

{
  "id": "AgentDeposit:019542f5-b3e7-1d02-0000-000000000001",
  "status": "PENDING",
  "sourceNetwork": "LIGHTNING",
  "sourceCurrency": "BTC",
  "destinationInternalAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "destinationCurrency": "USDB",
  "targetType": "LIGHTNING_INVOICE",
  "target": "lnbc1pndepositpp5...",
  "createdAt": "2026-10-09T18:00:00Z",
  "updatedAt": "2026-10-09T18:01:00Z",
  "sourceAmount": 31500,
  "estimatedReceiveAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc1pndepositpp5...",
    "shortUrl": "https://link.grid.money/deposit/Ab3dE7"
  },
  "expiresAt": "2026-10-09T18:05:00Z",
  "paidAfterExpiry": false
}

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).

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

201

application/json

Deposit created successfully

A deposit that converts funds from an external network into an internal account belonging to the agent's customer. 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.

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.

Show child attributes

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"

paymentLinks · object

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

Show child attributes

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.

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