> ## Documentation Index
> Fetch the complete documentation index at: https://agents-docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Internal Accounts

> Create and manage internal accounts

Internal accounts are Lightspark managed accounts that hold funds within the Grid platform. They allow you to receive deposits and send payments to external bank accounts or other payment destinations.

They are useful for holding funds on behalf of the platform or customers which will be used for instant, 24/7 quotes and transfers out of the system.

Internal accounts are created for both:

* **Platform-level accounts**: Hold pooled funds for your platform operations (rewards distribution, reconciliation, etc.)
* **Customer accounts**: Hold individual customer funds for their transactions

> [!NOTE]
>
> Internal accounts are automatically created when you onboard a customer, based
> on your platform's currency configuration. Platform-level internal accounts
> are created when you configure your platform with supported currencies.

> [!WARNING]
>
> On unregulated platforms, a customer's internal accounts aren't provisioned
> until you record their End User Terms acceptance in `agreementConsents`, and
> customer-scoped transactions are rejected with `403
>     END_USER_TERMS_NOT_ACCEPTED` until then. See
> [Disclosures](https://agents-docs.lightspark.com/payouts-and-b2b/onboarding/disclosures.md).

## How internal accounts work

Internal accounts act as an intermediary holding account in the payment flow:

1. **Deposit funds**: You or your customers deposit money into internal accounts using bank transfers (ACH, wire, PIX, etc.) or crypto transfers
2. **Hold balance**: Funds are held securely in the internal account until needed
3. **Send payments**: You initiate transfers from internal accounts to external destinations

Each internal account:

* Is denominated in a single currency (USD, EUR, etc.)
* Has a unique balance that you can query at any time
* Includes unique payment instructions for depositing funds
* Supports multiple funding methods depending on the currency

## Retrieving internal accounts

### List customer internal accounts

To retrieve all internal accounts for a specific customer, use the customer ID to filter the results:

```bash Request internal accounts for a customer theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
>       "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
>       "type": "INTERNAL_FIAT",
>       "status": "ACTIVE",
>       "balance": {
>         "amount": 50000,
>         "currency": {
>           "code": "USD",
>           "name": "United States Dollar",
>           "symbol": "$",
>           "decimals": 2
>         }
>       },
>       "totalBalance": {
>         "amount": 50000,
>         "currency": {
>           "code": "USD",
>           "name": "United States Dollar",
>           "symbol": "$",
>           "decimals": 2
>         }
>       },
>       "fundingPaymentInstructions": [
>         {
>           "accountOrWalletInfo": {
>             "reference": "FUND-ABC123",
>             "accountType": "USD_ACCOUNT",
>             "accountNumber": "9876543210",
>             "routingNumber": "021000021",
>             "bankName": "JP Morgan Chase",
>             "bankAddress": "270 Park Avenue, New York, NY 10017"
>           }
>         },
>         {
>           "accountOrWalletInfo": {
>             "accountType": "SOLANA_WALLET",
>             "assetType": "USDC",
>             "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
>           }
>         }
>       ],
>       "createdAt": "2025-10-03T12:00:00Z",
>       "updatedAt": "2025-10-03T14:30:00Z"
>     }
>   ],
>   "hasMore": false,
>   "totalCount": 1
> }
> ```

### Filter by currency

You can filter internal accounts by currency to find accounts for specific denominations:

```bash theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&currency=USD' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

### List platform internal accounts

To retrieve platform-level internal accounts (not tied to individual customers), use the platform internal accounts endpoint:

```bash theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/platform/internal-accounts' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

> [!NOTE]
>
> Platform internal accounts are useful for managing pooled funds, distributing
> rewards, or handling platform-level operations.

## Understanding funding payment instructions

Each internal account includes `fundingPaymentInstructions` that tell your customers how to deposit funds. The structure varies by payment rail and currency:

> [accordion] US ACH or wire transfers
>
> For USD accounts, instructions include routing and account numbers:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "USD_ACCOUNT",
>     "reference": "FUND-ABC123",
>     "accountNumber": "9876543210",
>     "routingNumber": "021000021",
>     "bankName": "JP Morgan Chase",
>     "bankAddress": "270 Park Avenue, New York, NY 10017"
>   }
> }
> ```
>
> > [!TIP]
> >
> > Each internal account has its own account number, and deposits are
> > credited by account number. The payer doesn't need to include the
> > `reference`. A deposit sent without it is still credited to this account.
>
> The account is held in the account owner's own legal name: the customer's
> `fullName` for an individual, or `businessInfo.legalName` for a business.
> A platform internal account is held in your platform's legal name. Show
> that name to payers as the beneficiary name, and ask them to copy it
> exactly on wires.

> [accordion] EUR account funding (SEPA)
>
> A `EUR_ACCOUNT` returns an IBAN, and deposits reach it over SEPA:
>
> ```json theme={null}
> {
>   "instructionsNotes": "Include reference in SEPA transfer description",
>   "accountOrWalletInfo": {
>     "accountType": "EUR_ACCOUNT",
>     "reference": "FUND-EUR789",
>     "iban": "DE89370400440532013000",
>     "swiftCode": "DEUTDEFF",
>     "bankName": "Deutsche Bank"
>   }
> }
> ```

> [accordion] Spark Stablecoin Funding
>
> For stablecoin accounts, using a Spark wallet as the funding source:
>
> ```json theme={null}
> {
>   "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs",
>   "instructionsNotes": "Use the invoice when making Spark payment",
>   "accountOrWalletInfo": {
>     "accountType": "SPARK_WALLET",
>     "assetType": "USDB",
>     "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
>   }
> }
> ```

> [accordion] Solana Stablecoin Funding
>
> For Solana wallet accounts, using a Solana wallet as the funding source:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "SOLANA_WALLET",
>     "assetType": "USDC",
>     "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
>   }
> }
> ```

> [accordion] Ethereum Stablecoin Funding
>
> For Ethereum L1 wallet accounts (USDC or USDT), using an Ethereum wallet as the funding source:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "ETHEREUM_WALLET",
>     "assetType": "USDT",
>     "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
>   }
> }
> ```

> [accordion] Tron Stablecoin Funding
>
> For Tron wallet accounts, using a Tron wallet as the funding source:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "TRON_WALLET",
>     "assetType": "USDT",
>     "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
>   }
> }
> ```

> [accordion] Plasma Stablecoin Funding
>
> For Plasma wallet accounts, using a Plasma wallet as the funding source:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "PLASMA_WALLET",
>     "assetType": "USDT",
>     "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
>   }
> }
> ```

> [accordion] Arbitrum Stablecoin Funding
>
> For Arbitrum wallet accounts, using an Arbitrum wallet as the funding source (USDC or USDT):
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "ARBITRUM_WALLET",
>     "assetType": "USDC",
>     "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
>   }
> }
> ```

> [accordion] Polygon Stablecoin Funding
>
> For Polygon wallet accounts, using a Polygon wallet as the funding source:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "POLYGON_WALLET",
>     "assetType": "USDC",
>     "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
>   }
> }
> ```

> [accordion] Base Stablecoin Funding
>
> For Base wallet accounts, using a Base wallet as the funding source:
>
> ```json theme={null}
> {
>   "accountOrWalletInfo": {
>     "accountType": "BASE_WALLET",
>     "assetType": "USDC",
>     "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
>   }
> }
> ```

## Checking account balances

The internal account balance reflects all deposits and withdrawals. The balance includes:

* **amount**: The balance amount in the smallest currency unit (cents for USD, centavos for MXN/BRL, etc.)
* **currency**: Full currency details including code, name, symbol, and decimal places

### Example balance check

```bash Fetch the balance of an internal account theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&currency=USD' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
>       "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
>       "type": "INTERNAL_FIAT",
>       "status": "ACTIVE",
>       "balance": {
>         "amount": 50000,
>         "currency": {
>           "code": "USD",
>           "name": "United States Dollar",
>           "symbol": "$",
>           "decimals": 2
>         }
>       },
>       "totalBalance": {
>         "amount": 50000,
>         "currency": {
>           "code": "USD",
>           "name": "United States Dollar",
>           "symbol": "$",
>           "decimals": 2
>         }
>       }
>     }
>   ],
>   "hasMore": false,
>   "totalCount": 1
> }
> ```

> [!TIP]
>
> Always check the `decimals` field in the currency object to correctly convert
> between display amounts and API amounts. For example, USD has 2 decimals, so
> an amount of 50000 represents \$500.00.

## Displaying funding instructions to customers

When customers need to deposit funds themselves, display the funding payment instructions in your application:

**1. Retrieve the internal account**

Fetch the customer's internal account for their desired currency using the API.

**2. Extract payment instructions**

Parse the `fundingPaymentInstructions` array and select the appropriate instructions based on your customer's preferred payment method.

```javascript theme={null}
const instructions = account.fundingPaymentInstructions[0];
const bankInfo = instructions.accountOrWalletInfo;
```

**3. Display instructions clearly**

Show the payment details prominently in your UI:

* Account holder name
* Bank name and routing information (account/routing number, CLABE, PIX key, etc.)
* Reference code (if provided)
* Any additional notes from `instructionsNotes`

> [!TIP]
>
> The unique banking details in each internal account automatically route
> deposits to the correct destination.

**4. Monitor for deposits**

Set up webhook listeners to receive notifications when deposits are credited to the internal account. The account balance will update automatically.

> [!NOTE]
>
> You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes.

## Best practices

> [accordion] Display complete funding instructions
>
> Ensure your customers have all the information needed to make deposits. Consider implementing:
>
> * Clear display of all banking details from `fundingPaymentInstructions`
> * Copy-to-clipboard functionality for account numbers and reference codes
> * Email/SMS confirmations with complete deposit instructions

> [accordion] Monitor account balances proactively
>
> Set up monitoring to alert customers when their balance is low:
>
> ```javascript theme={null}
> if (account.balance.amount < minimumThreshold) {
>   await notifyCustomer({
>     type: 'LOW_BALANCE',
>     account: account.id,
>     instructions: account.fundingPaymentInstructions
>   });
> }
> ```

> [accordion] Handle multiple currencies efficiently
>
> If your platform supports multiple currencies, organize internal accounts by currency in your UI:
>
> ```javascript theme={null}
> const accountsByCurrency = accounts.data.reduce((acc, account) => {
>   const code = account.balance.currency.code;
>   acc[code] = account;
>   return acc;
> }, {});
>
> // Quick lookup: accountsByCurrency['USD']
>
> ```

> [accordion] Cache account data appropriately
>
> Internal account details (especially funding instructions) rarely change, so you can cache them safely. However, always fetch fresh balance data before initiating transfers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.