--- title: "Create an agent deposit" method: POST path: "/agents/me/deposits" tags: ["Agent Operations"] --- # Create an agent deposit `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 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. ## Headers - `Idempotency-Key` string, required ## Request body - AgentDepositCreateRequest: 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. - `sourceNetwork` 'LIGHTNING' | 'BASE' | 'ETHEREUM' | 'SOLANA' | 'POLYGON' | 'ARBITRUM' | 'TRON', required: Network from which an agent customer can fund a deposit. `TRON` deposits support `USDT` only. - `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. - `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. - `amount` integer: 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. ## Response `201` Deposit created successfully - AgentDeposit: 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. - `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. - `sourceCurrency` string, required: Currency or asset the customer sends. - `sourceAmount` integer: Amount to send in the smallest unit of `sourceCurrency`, when the deposit quote fixes the source amount. - `destinationInternalAccountId` string, required: Internal account that receives the converted deposit. - `destinationCurrency` string, required: Currency credited to the destination internal account. - `estimatedReceiveAmount` CurrencyAmount - `amount` integer, required: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string: Full name of the currency - `symbol` string: Symbol of the currency - `decimals` integer: Number of decimal places for the currency - `targetType` 'LIGHTNING_INVOICE' | 'CHAIN_ADDRESS', required: Format of the payment target returned for an agent deposit. - `target` string, required: BOLT11 invoice when `targetType` is `LIGHTNING_INVOICE`; otherwise the address on `sourceNetwork` to which the customer sends funds. - `paymentLinks` object: Payment links for a `LIGHTNING` deposit. Absent for chain deposits. - `cashApp` string, uri, required: URL that opens the Lightning deposit in Cash App. - `shortUrl` string, uri: Shortened URL for the Lightning deposit, when available. - `expiresAt` string, date-time, nullable: Expiration time for a `LIGHTNING` invoice. Omitted or null for standing chain deposit addresses, which do not expire. - `createdAt` string, date-time, required: Time when the deposit was created. - `updatedAt` string, date-time, required: Time when the deposit was last updated. ## Other responses - `400`: Bad request - Unsupported deposit route or invalid amount - `401`: Unauthorized - `403`: Forbidden - Agents API is not enabled for the platform or the agent does not have the RECEIVE_FUNDS permission - `404`: Not found - The destination internal account does not belong to the agent's customer - `409`: Conflict - A chain deposit request for the same account, network and currency is still open: it has not been paid, and its 24-hour attribution window has not closed. The error reason gives the time that window closes; create a new request after it. - `500`: Internal service error - `503`: Service unavailable - The deposit provider is unavailable, or is holding the order for review. Retry with the same Idempotency-Key. ## Changes > 115 revisions in range; 2 not diffed. - **2026-10-28** `d996ddfb9d2b`: 5 info - added the optional property `details/missingFields` to the response with the `400` status - added the optional property `details/permission` to the response with the `403` status - added the optional property `details/policyDenialReason` to the response with the `403` status - added the optional property `details/refusalReason` to the response with the `400` status - …1 more - **2026-10-28** `5abf2bb56bcb`: 1 warning - added the new `CORRIDOR_UNDER_MAINTENANCE` enum value to the `code` response property for the response status `403` - **2026-10-26** `f11f1e76bdd7`: 1 warning - added the new `PURCHASE_CARD_LIMIT_REACHED` enum value to the `code` response property for the response status `409` - **2026-10-26** `0a6dad5815c7`: 1 warning - added the new `INVOICE_ALREADY_USED` enum value to the `code` response property for the response status `409` - **2026-10-24** `715332dcb111`: 1 warning - added the new `EXACT_AMOUNT_UNAVAILABLE` enum value to the `code` response property for the response status `400` [Operation history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/agents/me/deposits/post.md) --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) - [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)