Balance Accounts

Overview

A balance account is a USD account that holds funds. Bank deposits credit the balance instead of being swept onward, and the held balance can fund bank payouts or (when enabled for your organization) USDC/USDT transfers to an external or treasury wallet.

Open a balance account for a verified customer
Fund it by wiring to the account’s deposit instructions
Track the balance and its transaction history
Pay out by creating transfers sourced from the balance
Close it when the balance is drained

Prerequisites

The customer must be approved for USD balance accounts. Check the capabilities endpoint for USD_BALANCE:

import requests

response = requests.get(
    'https://api.infinite.dev/v1/customers/cus_abc123/capabilities',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/cus_abc123/capabilities',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
infinite api GET /v1/customers/cus_abc123/capabilities

What capabilities does customer cus_abc123 have?

curl -X GET "https://api.infinite.dev/v1/customers/cus_abc123/capabilities" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "capabilities": [
    { "capability": "USD_BALANCE", "status": "READY" }
  ]
}

IN_REVIEW means verification is still in progress; the capability is omitted entirely when the customer has no path to it yet.

Sandbox: skip real verification by setting the customer status to ACTIVE, then simulating the capability:

import requests

response = requests.put(
    'https://api.infinite.dev/v1/sandbox/customers/cus_abc123/capabilities',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'capabilities': ['USD_BALANCE'],
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/sandbox/customers/cus_abc123/capabilities',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      capabilities: ['USD_BALANCE'],
    }),
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
infinite api PUT /v1/sandbox/customers/cus_abc123/capabilities --body '{
  "capabilities": ["USD_BALANCE"]
}'

In sandbox, enable the USD_BALANCE capability for cus_abc123.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X PUT "https://api.infinite.dev/v1/sandbox/customers/cus_abc123/capabilities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["USD_BALANCE"]
  }'

USD_BALANCE becomes READY immediately, and the rest of this guide — opening the account, simulating deposits, reading balances — works as in production.

Open an account

One balance account per customer. Use an idempotency key so retries are safe:

import requests

response = requests.post(
    'https://api.infinite.dev/v1/balance-accounts',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
    },
    json={
        'customerId': 'cus_abc123',
    },
)

const response = await fetch('https://api.infinite.dev/v1/balance-accounts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
  },
  body: JSON.stringify({
    customerId: 'cus_abc123',
  }),
});

export INFINITE_API_KEY=YOUR_API_KEY
infinite api POST /v1/balance-accounts \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --body '{
  "customerId": "cus_abc123"
}'

Create a USD balance account for cus_abc123.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST "https://api.infinite.dev/v1/balance-accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "customerId": "cus_abc123"
  }'

The response is a standard account object with holdsBalance: true and the account’s bank deposit instructions in bankDetails — routing and account number for domestic wires, plus SWIFT details for international senders:

{
  "id": "acct_xyz789",
  "type": "VIRTUAL_BANK",
  "holdsBalance": true,
  "bankDetails": {
    "bankName": "Lead Bank",
    "routingNumber": "101019644",
    "accountNumber": "9876543210",
    "swiftCode": "LEADUS44"
  }
}

You can rediscover it later with GET /v1/accounts?holdsBalance=true.

If this balance account shares deposit coordinates with USD bank pay-in fixed routes (ACH, wire, or SWIFT), the two cannot both be enabled. Creating the balance account returns 409 while such a route is enabled; closing the balance account makes those routes available again. Crypto routes are unaffected.

A balance held on dedicated deposit coordinates can take a FIAT_TO_FIAT fixed route. Pass this account as sweepTargetAccountId on POST /v1/fixed-routes/virtual-bank-accounts. Deposits to that virtual account settle into the balance in the same currency, with no crypto leg. The route type is inferred. A non-zero developer fee returns Developer fees are not supported when the destination is a balance account. A currency mismatch returns Balance account currency must match the pay-in currency. A different banking partner, or deposit coordinates shared with the balance account, returns This pay-in route cannot settle into a balance account.

Fund it

No API call needed: wire (Fedwire) or SWIFT to the bankDetails above. When the deposit lands, the balance is credited automatically and your organization receives a balance.credited webhook:

{
  "type": "balance.credited",
  "data": {
    "accountId": "acct_xyz789",
    "customerId": "cus_abc123",
    "amount": "250000",
    "currency": "USD",
    "rail": "FEDWIRE"
  }
}

Amounts are in minor units (250000 = $2,500.00). Deposits credit net of any deposit fee, so the balance always mirrors funds actually held.

Sandbox

Simulate a deposit instead of sending a real wire. Use the funding-method account id (vba_…) from the create response — not a top-level acct_ id:

import requests

response = requests.post(
    'https://api.infinite.dev/v1/sandbox/accounts/vba_xyz789/fund-in',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'rail': 'WIRE',
        'amount': '2500.00',
        'currency': 'USD',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/sandbox/accounts/vba_xyz789/fund-in',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      rail: 'WIRE',
      amount: '2500.00',
      currency: 'USD',
    }),
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
infinite api POST /v1/sandbox/accounts/vba_xyz789/fund-in --body '{
  "rail": "WIRE",
  "amount": "2500.00",
  "currency": "USD"
}'

In sandbox, simulate a $2,500.00 wire deposit into vba_xyz789.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST "https://api.infinite.dev/v1/sandbox/accounts/vba_xyz789/fund-in" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "WIRE",
    "amount": "2500.00",
    "currency": "USD"
  }'

Check the balance

GET /v1/accounts/{id}/balance returns the available balance plus any amount pending on in-flight payouts:

import requests

response = requests.get(
    'https://api.infinite.dev/v1/accounts/acct_xyz789/balance',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/accounts/acct_xyz789/balance',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
infinite api GET /v1/accounts/acct_xyz789/balance

What's the balance of account acct_xyz789?

curl -X GET "https://api.infinite.dev/v1/accounts/acct_xyz789/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "accountId": "acct_xyz789",
  "currency": "USD",
  "available": {
    "currency": "USD",
    "exponent": 2,
    "value": "250000",
    "displayValue": "2500.00"
  },
  "pending": null
}

GET /v1/accounts/{id}/balance/transactions lists the history — deposit credits, payout debits, and reversals — newest first with cursor pagination.

Pay out

Create a transfer with the balance account as the source and paymentRail: "BALANCE". The destination is any of the customer’s external bank accounts, over ACH, RTP, WIRE, or SWIFT:

import requests

response = requests.post(
    'https://api.infinite.dev/v1/transfers',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'amount': {'currency': 'USD', 'rawValue': '100000'},
        'onBehalfOf': 'cus_abc123',
        'paymentReason': 'PAYMENT_FOR_GOODS_AND_SERVICES',
        'source': {
            'accountId': 'acct_xyz789',
            'paymentRail': 'BALANCE',
            'currency': 'USD',
        },
        'destination': {
            'accountId': 'eba_def456',
            'paymentRail': 'ACH',
            'currency': 'USD',
        },
    },
)

const response = await fetch('https://api.infinite.dev/v1/transfers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: { currency: 'USD', rawValue: '100000' },
    onBehalfOf: 'cus_abc123',
    paymentReason: 'PAYMENT_FOR_GOODS_AND_SERVICES',
    source: {
      accountId: 'acct_xyz789',
      paymentRail: 'BALANCE',
      currency: 'USD',
    },
    destination: {
      accountId: 'eba_def456',
      paymentRail: 'ACH',
      currency: 'USD',
    },
  }),
});

export INFINITE_API_KEY=YOUR_API_KEY
infinite api POST /v1/transfers --body '{
  "amount": { "currency": "USD", "rawValue": "100000" },
  "onBehalfOf": "cus_abc123",
  "paymentReason": "PAYMENT_FOR_GOODS_AND_SERVICES",
  "source": {
    "accountId": "acct_xyz789",
    "paymentRail": "BALANCE",
    "currency": "USD"
  },
  "destination": {
    "accountId": "eba_def456",
    "paymentRail": "ACH",
    "currency": "USD"
  }
}'

Pay $1,000.00 from balance account acct_xyz789 to eba_def456 by ACH on behalf of cus_abc123, for goods and services.

# With an agent key the assistant calls create_transfer (draft) then submit_transfer; with an org key run the CLI tab.

curl -X POST "https://api.infinite.dev/v1/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "currency": "USD", "rawValue": "100000" },
    "onBehalfOf": "cus_abc123",
    "paymentReason": "PAYMENT_FOR_GOODS_AND_SERVICES",
    "source": {
      "accountId": "acct_xyz789",
      "paymentRail": "BALANCE",
      "currency": "USD"
    },
    "destination": {
      "accountId": "eba_def456",
      "paymentRail": "ACH",
      "currency": "USD"
    }
  }'

The amount is held from the available balance when the transfer is submitted and finalized on completion; if the payout fails, the hold is re-credited. Insufficient balance fails the transfer before any funds move. Track the payout through the standard transfer lifecycle webhooks (transfer.created → transfer.processing → transfer.completed). Balance payouts to banks are USD to USD. Per-transaction limits are $1M for ACH/RTP and $20M for WIRE/SWIFT; a small fee buffer is reserved under each cap, so payouts at exactly the limit are rejected — keep amounts a little below it.

Pay out as stablecoins

When enabled for your organization, the same balance account can fund a transfer to an external wallet or treasury wallet in USDC or USDT. Use source.paymentRail: "BALANCE" with a crypto destination currency and rail. Developer fees are supported the same way as other onramps. Contact your Infinite representative to enable this path.

Close the account

import requests

response = requests.delete(
    'https://api.infinite.dev/v1/balance-accounts/acct_xyz789',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/balance-accounts/acct_xyz789',
  {
    method: 'DELETE',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
infinite api DELETE /v1/balance-accounts/acct_xyz789

Close balance account acct_xyz789.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X DELETE "https://api.infinite.dev/v1/balance-accounts/acct_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Closing requires the balance to be fully settled at zero and no payouts in flight — pay out any remaining funds first (409 otherwise). In the rare case where the account shows $0.00 available but closing is still rejected, a ledger discrepancy is pending resolution — contact support. After closing, the account no longer accepts deposits, and USD bank pay-in fixed routes become available to the customer again.

Get started

Core Concepts

Guides

Overview

Prerequisites

Open an account

Fund it

Sandbox

Check the balance

Pay out

Pay out as stablecoins

Close the account

Reference

​Overview

​Prerequisites

​Open an account

​Fund it

​Sandbox

​Check the balance

​Pay out

​Pay out as stablecoins

​Close the account

​Reference

Overview

Prerequisites

Open an account

Fund it

Sandbox

Check the balance

Pay out

Pay out as stablecoins

Close the account

Reference