LIlightsparkdev
Agent Operations

Create an agent deposit

Changed on

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

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/agents/me/deposits
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring required
Example:550e8400-e29b-41d4-a716-446655440000

Unique identifier used to return the same deposit for retries.

Request body

sourceNetwork'LIGHTNING' | 'BASE' | 'ETHEREUM' | 'SOLANA' | 'POLYGON' | 'ARBITRUM' | 'TRON' required

Network from which an agent customer can fund a deposit. TRON deposits support USDT only.

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

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

amountinteger

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.

Example request

{
  "sourceCurrency": "USD",
  "destinationInternalAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "amount": 2000
}

Response

Deposit created successfully

idstring required

System-generated unique deposit identifier.

status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'REFUNDED' required

Current state of an agent deposit.

sourceNetwork'LIGHTNING' | 'BASE' | 'ETHEREUM' | 'SOLANA' | 'POLYGON' | 'ARBITRUM' | 'TRON' required

Network from which an agent customer can fund a deposit. TRON deposits support USDT only.

sourceCurrencystring required

Currency or asset the customer sends.

sourceAmountinteger

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

destinationInternalAccountIdstring required

Internal account that receives the converted deposit.

destinationCurrencystring required

Currency credited to the destination internal account.

targetType'LIGHTNING_INVOICE' | 'CHAIN_ADDRESS' required

Format of the payment target returned for an agent deposit.

targetstring required

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

expiresAtstring date-time nullable

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

createdAtstring date-time required

Time when the deposit was created.

updatedAtstring date-time required

Time when the deposit was last updated.

Example response

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

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5abf2bb56bcbRevision changes
    • warning

      added the new CORRIDOR_UNDER_MAINTENANCE enum value to the response property for the response status