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

> ## Agent Instructions
> If you are an AI assistant operating Infinite for a user, read the skill first: https://docs.infinite.dev/agent-skill.md (setup per host, tool reference, rules for moving money, journeys).
> When operating Infinite for a user, use the MCP server. Sign in at https://bot.api.infinite.dev/mcp (production, acts as the user) or send `Authorization: Bearer <key>` to https://bot.api.infinite.dev/mcp/sse. Prefer its tools over raw HTTP; use REST only for steps no tool covers, and check `get_endpoint_schema` before guessing a request shape.
> Net-new Infinite Connect (org_connect) is operator-assisted: do not grant end users shared org_connect Auth Kit membership or the shared platform org API key — those credentials are org-wide on /v1. BYO org keys onboard under that customer's org id. Operator sessions should show org_connect in get_organization_info.
> The key decides the tools. Every organization key (`sk_sandbox_…` / `sk_live_…`) gets docs, onboarding, `get_account_balance`, and request logs for your own organization. BYO organizations add payees an agent will pay with `create_payee` (payable once ACTIVE). Platform Connect sessions instead get bound-customer payment lookups (`get_quote`, `get_transfer`, `list_transfers`, `list_account_balances`), payee drafts (`create_payee_draft` / `get_payee_draft`; screening only, never payable), and transfer drafts that wait for Infinite approval (`create_transfer_draft` / `get_transfer_draft`; never POST /v1/transfers). Where offered, platform `create_transfer` files a real transfer that Infinite holds in review before funding; it cannot be submitted from DRAFT.
> An agent key (`sk_sandbox_agent_…` / `sk_live_agent_…`) moves money within that agent's limits: `create_transfer` → `submit_transfer` → `wait_for_transfer`.
> On sandbox organization-key sessions, `sandbox_approve_customer` (makes the capabilities you pass READY, and related ones may turn READY too; `request_capabilities` is not needed), `sandbox_fund_account`, and `sandbox_complete_transfer` stand in for verification, funding, and settlement, so a whole flow runs from MCP. BYO keys can pass `customerId` on each call without binding; platform sessions must bind a customer first (`create_business_customer` auto-binds, or send `X-Infinite-On-Behalf-Of`).
> When searching documentation without a key, use the docs MCP at https://docs.infinite.dev/mcp.
> Start in sandbox (https://sandbox.api.infinite.dev). Do not use production unless the user explicitly asks.
> Confirm amount, currency, and payee with the user before any payment is submitted. Pass the invoice number as `reference` on `create_transfer`; the summary says what the payee will see.
> REST amounts are integer minor units (`"4000"` = 40.00 USD). MCP payment tools take exact decimal strings (`"40.00"`). Never mix them.
> Agent denials return `403 { denial: { code, message, window, limit, used, remaining, attemptedAmount, currency }, hint }` with decimal amounts; per-transfer denials omit `used` and `remaining`. Report them to the user; do not work around them.

# Accounts

> Infinite wallets (inw_ mailbox vs treasury vault), external wallets (ewa_ guards), virtual bank accounts, and why vwa_ is not a crypto deposit wallet

Accounts are the financial infrastructure layer in Infinite. They represent where funds are held and how they move -- whether through traditional banking rails or blockchain networks.

## Overview

Infinite uses a typed account system where each account serves a specific purpose. Accounts are always linked to a [customer](/concepts/customers) and have distinct creation endpoints.

Think in **roles**, not just type names. The same `INFINITE_WALLET` (`inw_`) type is used for a deposit mailbox and for a treasury vault.

| Role | Type | Prefix | What it is |
| - | - | - | - |
| Fiat mailbox | `VIRTUAL_BANK` | `vba_` | Bank details we issue so a customer can send ACH, wire, or SWIFT |
| Crypto mailbox | `INFINITE_WALLET` (`walletType: VIRTUAL`) | `inw_` | Dedicated deposit address from `POST /v1/fixed-routes/virtual-wallets` |
| Vault (custodial) | `INFINITE_WALLET` (treasury) | `inw_` | Where Infinite holds crypto. Auto-provisioned. Source of withdrawals |
| Their bank | `EXTERNAL_BANK` | `eba_` | Customer's own bank account. Payout destination |
| Their wallet | `EXTERNAL_WALLET` | `ewa_` | Customer's own address. Payout, sweep target, or a co-signer / guard they control |
| USD / stablecoin balance | `VIRTUAL_BANK` / `PROVIDER_BALANCE` | `vba_` / `pba_` | Held balance, not a sweep |

## Infinite Wallets (`INFINITE_WALLET`, `inw_`)

Blockchain wallets managed by Infinite on behalf of your customers. There is **no public create endpoint** for treasury wallets -- they are provisioned automatically when a customer is approved. List them with `GET /v1/accounts?type=INFINITE_WALLET`.

Three jobs share this type:

* **Treasury (vault)** -- holds balances; source for withdrawals and payouts
* **Transaction** -- system-controlled address used while a one-off transfer is in flight
* **Deposit mailbox (`walletType: VIRTUAL`)** -- created by [crypto fixed routes](/concepts/fixed-routes). Unique receive address that auto-sweeps to a bank or wallet

Do not treat a treasury `inw_` as something you can sandbox-fund. [Account fund-in](/api-reference/sandbox/simulate-account-funding) only accepts funding-method ids (`vba_`, `vwa_`, `pba_`). To credit a vault in sandbox, pick a [fixed route](/concepts/fixed-routes) whose sweep target is that vault, then [simulate a deposit](/api-reference/sandbox/simulate-a-fixed-route-source-deposit) with the route's **source** account id (`vba_…` or mailbox `inw_…`). Funds land on the destination, not the source mailbox. Then create a transfer **from** the vault.

You cannot attach a third-party key as a co-signer on an Infinite wallet. If you need a customer-controlled address (a guard, guardian, or self-custodial destination), create an [external wallet](#external-wallets).

Supported address types: `EVM`, `SOLANA`, `TRON`, `BITCOIN`

## External Bank Accounts

Bank accounts owned by your customers at external institutions. Used as payout destinations for fiat transfers.

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.infinite.dev/v1/external-bank-accounts',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      json={
          'customerId': 'cus_abc123',
          'beneficiaryName': 'Acme Corp',
          'paymentRails': ['swift'],
          'swiftBic': 'CHASUS33',
          'accountNumber': '1234567890',
          'beneficiaryAddress': {
              'addressLine1': '123 Main St',
              'city': 'New York',
              'state': 'NY',
              'postalCode': '10001',
              'country': 'US',
          },
      },
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.infinite.dev/v1/external-bank-accounts', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId: 'cus_abc123',
      beneficiaryName: 'Acme Corp',
      paymentRails: ['swift'],
      swiftBic: 'CHASUS33',
      accountNumber: '1234567890',
      beneficiaryAddress: {
        addressLine1: '123 Main St',
        city: 'New York',
        state: 'NY',
        postalCode: '10001',
        country: 'US',
      },
    }),
  });
  ```

  ```bash CLI theme={null}
  export INFINITE_API_KEY=sk_live_...
  infinite api POST /v1/external-bank-accounts --body '{
    "customerId": "cus_abc123",
    "beneficiaryName": "Acme Corp",
    "paymentRails": ["swift"],
    "swiftBic": "CHASUS33",
    "accountNumber": "1234567890",
    "beneficiaryAddress": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }'
  ```

  ```text MCP theme={null}
  Add a SWIFT bank account for cus_abc123: beneficiary Acme Corp, BIC CHASUS33, account number 1234567890, address 123 Main St, New York, NY 10001, US.

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

  ```bash cURL theme={null}
  curl -X POST "https://api.infinite.dev/v1/external-bank-accounts" \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cus_abc123",
      "beneficiaryName": "Acme Corp",
      "paymentRails": ["swift"],
      "swiftBic": "CHASUS33",
      "accountNumber": "1234567890",
      "beneficiaryAddress": {
        "addressLine1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      }
    }'
  ```
</CodeGroup>

Required fields vary by payment rail. See the [API reference](/api-reference/external-bank-accounts/create-an-external-account) for full details.

## External Wallets

Third-party blockchain wallets owned by your customers. Infinite does not hold the keys. Use them as payout destinations, fixed-route sweep targets, or a customer-controlled guard address.

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.infinite.dev/v1/external-wallets',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      json={
          'customerId': 'cus_abc123',
          'walletAddress': '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7',
          'chains': ['ETHEREUM', 'BASE'],
      },
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.infinite.dev/v1/external-wallets', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId: 'cus_abc123',
      walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7',
      chains: ['ETHEREUM', 'BASE'],
    }),
  });
  ```

  ```bash CLI theme={null}
  export INFINITE_API_KEY=sk_live_...
  infinite api POST /v1/external-wallets --body '{
    "customerId": "cus_abc123",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "chains": ["ETHEREUM", "BASE"]
  }'
  ```

  ```text MCP theme={null}
  Add external wallet 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 for cus_abc123 on Ethereum and Base.

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

  ```bash cURL theme={null}
  curl -X POST "https://api.infinite.dev/v1/external-wallets" \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cus_abc123",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "chains": ["ETHEREUM", "BASE"]
    }'
  ```
</CodeGroup>

The response id is `ewa_…`. Status starts `IN_REVIEW` and becomes `ACTIVE` after screening. See [Create an external wallet](/api-reference/external-wallets/create-an-external-wallet).

## Virtual Bank Accounts

Fiat bank accounts provisioned within Infinite's banking partners. Used for receiving fiat deposits via ACH, wire, SEPA, SWIFT, and similar rails.

These are typically created as part of a [fixed route](/concepts/fixed-routes) (`POST /v1/fixed-routes/virtual-bank-accounts`) rather than standalone. Each route gets its own account number, so the deposit identifies itself -- no memo required.

A USD [balance account](/guides/balance-accounts) is also a `vba_` that **holds** funds instead of sweeping. A separate [fixed route](/concepts/fixed-routes#fiat-deposits-into-a-usd-balance) can use that balance account as its sweep target, so deposits to a dedicated account number credit the balance with no conversion.

## Virtual wallets (`vwa_`) vs crypto deposit wallets

The `vwa_` prefix is a funding-method virtual wallet used in some products (for example card funding). It is **not** what `POST /v1/fixed-routes/virtual-wallets` returns.

That endpoint creates an `INFINITE_WALLET` (`inw_`) with `walletType: VIRTUAL` -- a dedicated crypto mailbox. Sandbox fund-in on `vwa_` will not credit that mailbox. To test the route, [simulate-deposit](/api-reference/sandbox/simulate-a-fixed-route-source-deposit) with the mailbox (source) account id; the sweep credits the route destination.

## ID Prefixes

Each account type has a distinct ID prefix:

| Type | Prefix | Example |
| - | - | - |
| Infinite Wallet | `inw_` | `inw_abc123` |
| External Bank Account | `eba_` | `eba_abc123` |
| External Wallet | `ewa_` | `ewa_abc123` |
| Virtual Bank Account | `vba_` | `vba_abc123` |
| Virtual Wallet | `vwa_` | `vwa_abc123` |
| Provider / stablecoin balance | `pba_` | `pba_abc123` |

## Account Status

| Status | Description |
| - | - |
| `IN_REVIEW` | Account created, awaiting approval |
| `ACTIVE` | Account operational |
| `CLOSED` | Account permanently closed |

Account status is read-only. Once an external bank or proxy account is `ACTIVE`, you can permanently close it with [`POST /v1/external-bank-accounts/{id}/close`](/api-reference/external-bank-accounts/close-an-external-account). Accounts still `IN_REVIEW` cannot be closed. Closed accounts cannot be used as transfer or FX destinations, and fixed routes that sweep to them are disabled.

## Retrieving Accounts

### List accounts for a customer

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.infinite.dev/v1/accounts',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      params={'customerId': 'cus_abc123'},
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://api.infinite.dev/v1/accounts?customerId=cus_abc123',
    {
      headers: {
        Authorization: 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
    },
  );
  ```

  ```bash CLI theme={null}
  export INFINITE_API_KEY=sk_live_...
  infinite accounts list --limit 10
  # Or filter via escape hatch:
  infinite api GET /v1/accounts --query customerId=cus_abc123
  ```

  ```text MCP theme={null}
  List all accounts for customer cus_abc123.
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.infinite.dev/v1/accounts?customerId=cus_abc123" \
    -H "Authorization: Bearer sk_live_..."
  ```
</CodeGroup>

### Get an account by ID

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.infinite.dev/v1/accounts/inw_abc123',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://api.infinite.dev/v1/accounts/inw_abc123',
    {
      headers: {
        Authorization: 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
    },
  );
  ```

  ```bash CLI theme={null}
  export INFINITE_API_KEY=sk_live_...
  infinite accounts get inw_abc123
  ```

  ```text MCP theme={null}
  Show me account inw_abc123.
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.infinite.dev/v1/accounts/inw_abc123" \
    -H "Authorization: Bearer sk_live_..."
  ```
</CodeGroup>

## Next Steps

Once accounts are set up, you can create [transfers](/concepts/transfers) to move funds between them.

<CardGroup cols={2}>
  <Card title="Transfers" icon="arrow-right-arrow-left" href="/concepts/transfers">
    Move funds between accounts across fiat and crypto rails
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/accounts/get-all-accounts">
    Full API reference for account endpoints
  </Card>
</CardGroup>


## Related topics

- [Get virtual accounts by account](/api-reference/accounts/get-virtual-accounts-by-account.md)
- [Balance Accounts](/guides/balance-accounts.md)
- [Create an external account](/api-reference/external-bank-accounts/create-an-external-account.md)
- [Get account by ID](/api-reference/accounts/get-account-by-id.md)
- [Close an external account](/api-reference/external-bank-accounts/close-an-external-account.md)