Get an agent deposit

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/deposits/{depositId} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/deposits/{depositId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/deposits/{depositId}")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "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",
  "achPull": {
    "externalAccountId": "ExternalAccount:019542f5-b3e7-1d02-0000-000000000003",
    "accountLast4": "6789",
    "authorization": {
      "textVersion": "ach-pull-v1",
      "text": "I authorize Lightspark Group, Inc. and its partner bank to debit $20.00 once from my CHECKING account ending ••6789 at Chase on or after November 9, 2026, to add funds to my Lightspark Agents account. This authorizes a single debit only. I can revoke it before the debit is sent by cancelling it on this page or by contacting support@lightspark.com; revoking does not affect a debit already sent.",
      "textSha256": "e341cec8130241e0b34961bb2541adc23dca596c8bf4a68468a65037d4aaaf3d",
      "id": "DebitAuthorization:019542f5-b3e7-1d02-0000-000000000004",
      "authorizedAt": "2026-10-09T18:01:00Z",
      "revokedAt": "2026-10-09T18:01:30Z"
    },
    "limits": {
      "perPullLimit": 100000,
      "rolling7DayRemaining": 200000,
      "rolling30DayRemaining": 500000
    },
    "returnCode": "R01"
  },
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc1pndepositpp5...",
    "shortUrl": "https://link.grid.money/deposit/Ab3dE7"
  },
  "expiresAt": "2026-10-09T18:05:00Z",
  "paidAfterExpiry": false
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

GET

agents

{agentId}

deposits

{depositId}

Get an agent deposit

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/deposits/{depositId} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/deposits/{depositId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/deposits/{depositId}")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "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",
  "achPull": {
    "externalAccountId": "ExternalAccount:019542f5-b3e7-1d02-0000-000000000003",
    "accountLast4": "6789",
    "authorization": {
      "textVersion": "ach-pull-v1",
      "text": "I authorize Lightspark Group, Inc. and its partner bank to debit $20.00 once from my CHECKING account ending ••6789 at Chase on or after November 9, 2026, to add funds to my Lightspark Agents account. This authorizes a single debit only. I can revoke it before the debit is sent by cancelling it on this page or by contacting support@lightspark.com; revoking does not affect a debit already sent.",
      "textSha256": "e341cec8130241e0b34961bb2541adc23dca596c8bf4a68468a65037d4aaaf3d",
      "id": "DebitAuthorization:019542f5-b3e7-1d02-0000-000000000004",
      "authorizedAt": "2026-10-09T18:01:00Z",
      "revokedAt": "2026-10-09T18:01:30Z"
    },
    "limits": {
      "perPullLimit": 100000,
      "rolling7DayRemaining": 200000,
      "rolling30DayRemaining": 500000
    },
    "returnCode": "R01"
  },
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc1pndepositpp5...",
    "shortUrl": "https://link.grid.money/deposit/Ab3dE7"
  },
  "expiresAt": "2026-10-09T18:05:00Z",
  "paidAfterExpiry": false
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Path Parameters

agentId

string

required

System-generated unique agent identifier

depositId

string

required

System-generated unique deposit identifier

Response

Successful operation

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.

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,

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.

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"

achPull

object

ACH debit details. Present only for ACH_PULL.

Show child attributes

paymentLinks

object

Payment links present only for a LIGHTNING deposit.

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

Using the API

API documentation

Get an agent deposit

Authorizations

Path Parameters

Response