> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infinite.net/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), transfer drafts that wait for Infinite approval (`create_transfer_draft` / `get_transfer_draft`; never POST /v1/transfers), and with a bound customer, `create_transfer` (real POST /v1/transfers, forced IN_REVIEW until Infinite ops approve; not on BYO org keys). An agent key (`sk_sandbox_agent_…` / `sk_live_agent_…`) on a **PAYMENT**-role agent moves money within that agent's limits: `create_transfer` (draft) → `submit_transfer` → `wait_for_transfer`, without per-payment Infinite approval. **PAYMENT_OPERATIONS** agent keys are read-only (no `get_quote`, `create_transfer`, or `submit_transfer`; use `get_quote_by_id` and `list_transfers` on the pinned customer).
> 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.

# Connect

> Onboard your customers, issue accounts, and move money on their behalf with the existing Infinite API

Connect is how a platform or marketplace runs on Infinite: onboard each end customer through verification, issue them accounts, then move money with your organization API key and `onBehalfOf` set to that customer.

There is no separate Connect resource or funds-flow toggle. The flow is three stages — onboard, issue accounts, transfer — each using existing API calls.

```mermaid theme={null}
flowchart LR
  A[Create customer] --> B[Verify KYC / KYB]
  B --> C[Customer ACTIVE]
  C --> D[Issue accounts]
  D --> E["Transfer with onBehalfOf"]
```

## Who this is for

| You are… | Use Connect for… |
| - | - |
| A marketplace or B2B platform | Onboarding sellers / buyers, paying them out, collecting from them |
| An embedded finance product | Hosted verification in your brand, accounts under your customers |
| An agent platform | Same path — each end business is a [customer](https://docs.infinite.net/concepts/customers.md); agents act under that customer (see [Agents](https://docs.infinite.net/concepts/agents.md)) |

First-party (moving your own money) does not need Connect. Create accounts and [transfers](https://docs.infinite.net/concepts/transfers.md) for your organization's own customer record.

## 1. Onboard your customer

Create a customer under your organization, then verify them.

> [!NOTE]
>
> The HTTP fragments below are illustrative. Use the API reference examples (Python, TypeScript, CLI, cURL) or your HTTP client with authentication to execute requests.

### Create

```text theme={null}
POST /v1/customers/businesses
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "customerName": "Acme Sellers LLC",
  "email": "ops@acme-sellers.example",
  "countryCode": "US"
}
```

Use `POST /v1/customers/individuals` when the end user is a person. See [Customers](https://docs.infinite.net/concepts/customers.md).

### Verify

**Hosted link (recommended for platforms):** send the customer Infinite's hosted KYC / KYB UI.

```text theme={null}
POST /v1/verification/initiate

{
  "name": "Acme Sellers LLC",
  "email": "ops@acme-sellers.example",
  "type": "BUSINESS",
  "countryCode": "US",
  "customerId": "cus_abc123"
}
```

The response includes a verification URL. This endpoint does not accept `Idempotency-Key`; reuse behavior depends on existing session state and can return `400` if a session is already pending. For associated individuals (UBOs), use [generate a verification link for an associated entity](https://docs.infinite.net/api-reference/customers/generate-verification-link-for-associated-entity.md).

**API-driven:** collect data in your UI, then save and submit verification on the customer. Full flow: [Verification](https://docs.infinite.net/concepts/verification.md).

Wait until the customer is `ACTIVE` and the [capabilities](https://docs.infinite.net/api-reference/customers/get-customer-capabilities.md) you need are `READY` before issuing payment accounts or creating transfers. `ACTIVE` is compliance approval only — individual rails can stay `IN_REVIEW` until their onboarding finishes. Subscribe to exact [webhook](https://docs.infinite.net/guides/webhooks.md) event names such as `customer.status_changed` and `customer.capability.updated` (endpoint `filterTypes` match exact strings — wildcards like `customer.*` deliver nothing). For transfer and external-account events, use the same exact names as checklist step 6. Poll `GET /v1/customers/{id}` for customer status; do not use `GET /v1/verification/customers/{id}` for approval — it returns verification-session state (`ACTIVE`, `SUBMITTED`, …), not customer compliance status.

| Status | Meaning (onboarding-focused) |
| - | - |
| `DRAFT` | Still collecting data |
| `IN_REVIEW` | Submitted, under review |
| `NEED_ACTIONS` | RFI outstanding — see [RFIs](https://docs.infinite.net/api-reference/rfis/list-rfis.md) |
| `ACTIVE` | Compliance approved — check capabilities before transacting |
| `REJECTED` | Not approved |
| `SUSPENDED` | Temporarily blocked — stop transacting until resolved |
| `INACTIVE` | Offboarded — stop transacting |

Full lifecycle: [Customers](https://docs.infinite.net/concepts/customers.md).

## 2. Issue accounts

Once the customer is `ACTIVE` and the relevant capabilities are `READY`, open the accounts that customer will hold and pay from.

| Need | How |
| - | - |
| Hold USD | [Balance accounts](https://docs.infinite.net/guides/balance-accounts.md) — `POST /v1/balance-accounts` when `USD_BALANCE` is `READY` on [capabilities](https://docs.infinite.net/api-reference/customers/get-customer-capabilities.md) |
| Crypto treasury | Infinite wallet (`inw_`) — auto-provisioned on approval; list with `GET /v1/accounts?type=INFINITE_WALLET&customerId=cus_abc123` |
| Standing deposit mailbox | [Fixed routes](https://docs.infinite.net/concepts/fixed-routes.md) — `POST /v1/fixed-routes/virtual-bank-accounts` or `/virtual-wallets` |
| Pay out to their bank / wallet | [External bank](https://docs.infinite.net/api-reference/external-bank-accounts/create-an-external-account.md) (`eba_`) or [external wallet](https://docs.infinite.net/api-reference/external-wallets/create-an-external-wallet.md) (`ewa_`) — start `IN_REVIEW` until screening clears |

Accounts always belong to a `cus_`. Your org key creates them; the customer owns the balances.

External accounts emit `external_account.in_review`, `external_account.approved`, and `external_account.rejected` (subscribe with those exact names if you filter webhooks). Do not treat a destination as payable until it is `ACTIVE`.

## 3. Move money on their behalf

Every transfer takes `onBehalfOf` set to the end customer's id. Your organization API key signs the request; the customer is the principal on the payment.

```text theme={null}
POST /v1/transfers
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002

{
  "onBehalfOf": "cus_abc123",
  "amount": {
    "currency": "USD",
    "rawValue": "25000"
  },
  "source": {
    "currency": "USD",
    "paymentRail": "BALANCE",
    "accountId": "vba_seller_balance"
  },
  "destination": {
    "currency": "USD",
    "paymentRail": "ACH",
    "accountId": "eba_seller_bank"
  },
  "paymentReason": "PAYMENT_FOR_GOODS_AND_SERVICES",
  "confirm": true
}
```

Use `paymentRail: "BALANCE"` when the source is a held USD balance account. Generate one high-entropy `Idempotency-Key` per logical transfer, persist it with your payout record, and send the **same** key on every retry (timeouts included). With `confirm: true`, a fresh key on retry can create a second submitted transfer. See [Idempotency](https://docs.infinite.net/guides/idempotency.md).

Monitor payouts with the same exact transfer webhook names as checklist step 6: `transfer.completed`, `transfer.failed`, `transfer.updated`, `transfer.cancelled`, and `transfer.reversed`. Cancellations emit `transfer.cancelled`, not `transfer.updated`.

### Payees who are not the customer

When the destination is a third-party payee (not the customer's own external account), create a [counterparty](https://docs.infinite.net/api-reference/counterparties/create-a-counterparty.md) (`cp_`), attach their external account with `isThirdParty: true` and that `counterpartyId` (both are required — omitting `isThirdParty` returns `400`), wait until the account is `ACTIVE`, then pass `counterpartyId` on the transfer.

Counterparties are organization-scoped and can be linked to more than one customer through accounts. Screening still runs on the destination before it becomes payable.

### Platform take-rate

Take your cut in the settlement path with `developerFeeFixed` and `developerFeePercent` on transfers and fixed routes when the route supports fees. The API rejects fees on balance-account destinations and on some fiat deposit routes — confirm support for your corridor before relying on a take-rate. See [Transfers — Developer fees](https://docs.infinite.net/concepts/transfers.md#developer-fees), [Agents — Bill](https://docs.infinite.net/concepts/agents.md#bill), and [Fixed routes](https://docs.infinite.net/concepts/fixed-routes.md).

### Terms of service (API-driven onboarding)

When you collect verification data in your UI instead of a hosted verification link, record Terms of Service acceptance before verification submit.

**Recommended:** persist verification inputs that affect which agreements apply (requested capabilities, industry, and related profile fields) before generating a link, or pass the primary customer's `verificationSessionId` on generate — otherwise hosted-context can omit a required agreement block and submit returns `400` for incomplete ToS. Then call [`POST /v1/tos/generate`](https://docs.infinite.net/api-reference/terms-of-service/generate-hosted-tos-acceptance-link) with the customer's id (and `verificationSessionId` for associated-person acceptance). Send the end user the returned `acceptanceUrl` so they complete every agreement Infinite requires for that customer. Poll [`GET /v1/tos/{id}`](https://docs.infinite.net/api-reference/terms-of-service/get-tos-acceptance-status) until `acceptedAt` is set, then pass the id as `metadata.infiniteTosAcceptanceId` on verification submit. Do not call [`POST /v1/tos/{id}/accept`](https://docs.infinite.net/api-reference/terms-of-service/accept-terms-of-service) on the user's behalf.

**Custom UI (advanced):** call [`POST /v1/tos`](https://docs.infinite.net/api-reference/terms-of-service/initiate-tos-acceptance), then [`GET /v1/tos/{id}/hosted-context`](https://docs.infinite.net/api-reference/terms-of-service/get-hosted-tos-page-context) to learn which additional agreement blocks apply for that customer. On [`POST /v1/tos/{id}/accept`](https://docs.infinite.net/api-reference/terms-of-service/accept-terms-of-service), set `infiniteAgreementsAccepted: true` and set each matching agreement field to `true` when hosted-context shows that block is required — otherwise submit can return `400`. Use the additional-agreement flags from hosted-context and the corresponding accept-body fields documented in the API reference (same names, different prefixes).

**Shortcut:** `hasAgreedToTos: true` on verification submit uses the API shortcut: Infinite's core agreements are always recorded, and additional regional or rail agreements that onboarding routing can infer are pre-filled in the same step. When no agreement block still requires explicit end-user acceptance, the record is fully accepted. If any block still requires explicit acceptance, `acceptedAt` stays null until the customer completes hosted acceptance or a full accept call — use [`POST /v1/tos/generate`](https://docs.infinite.net/api-reference/terms-of-service/generate-hosted-tos-acceptance-link) or manual accept for those cases, and confirm with [`GET /v1/tos/{id}`](https://docs.infinite.net/api-reference/terms-of-service/get-tos-acceptance-status) and [`GET /v1/customers/{id}/compliance`](https://docs.infinite.net/api-reference/customers/get-customer-compliance-requirements) before submit.

Customer create/update does not record ToS.

## AI assistants (MCP)

Platforms can wire the [Infinite MCP server](https://docs.infinite.net/guides/mcp.md) into any MCP-capable assistant or IDE with an organization API key or Auth Kit sign-in.

| Mode | Who | Transfers |
| - | - | - |
| **Platform Connect** | Infinite Connect session with a bound customer (`bind_session_customer` or `X-Infinite-On-Behalf-Of` — see header rules below) | `create_transfer` calls `POST /v1/transfers` with `confirm: true` for that customer after you confirm amount, payee, and rail with the end user. Every transfer is forced to **`IN_REVIEW`** until Infinite operations approve it; track with `get_transfer` / `list_transfers` |
| **Agent key** | `sk_*_agent_*` for an [`agt_`](https://docs.infinite.net/concepts/agents) | Draft + `submit_transfer` within agent limits and allowlist — not held in ops `IN_REVIEW` for routine payouts |
| **BYO org key** | Your own organization | MCP does not create transfers — use REST or an agent key |

Header rules (MCP):

* OAuth/Auth Kit sign-in: `X-Infinite-On-Behalf-Of` is forbidden. Bind with `bind_session_customer` using the `continuationToken` from `create_business_customer`.
* Delegation (in‑app assistant) sessions: header is allowed when it matches the pinned customer in the delegation token; without a pinned claim it is allowed only for customers owned by your organization.
* API keys: header is allowed only for customers owned by your organization.

Net-new Connect OAuth sessions cannot set the header; create the business with `create_business_customer`, then `bind_session_customer` (or use `continuationToken` after disconnect). See [Platform Connect transfers](https://docs.infinite.net/guides/mcp.md#platform-connect-transfers-organization-key) and [Agents](https://docs.infinite.net/concepts/agents.md#building-blocks).

## Child organizations (optional)

[`POST /v1/organizations/{organizationId}/children`](https://docs.infinite.net/api-reference/organizations/create-a-child-organization) creates a separate organization under yours. That is a **tenancy** feature (separate keys, data, and config), capability-gated — not required for Connect or third-party funds flow.

Use child orgs when you need hard isolation between brands or environments. Use customers + `onBehalfOf` when you are one platform serving many end businesses.

## Checklist

1. Create `cus_` under your org
2. Hosted or API verification → wait for `ACTIVE` and required capabilities `READY`
3. Issue balance / wallet / fixed-route / external accounts
4. Screen payees (`cp_` + external accounts → `ACTIVE`)
5. `POST /v1/transfers` with `onBehalfOf` and a persisted `Idempotency-Key` reused on retries
6. Subscribe with exact event names (or omit `filterTypes` for all): `customer.status_changed`, `customer.capability.updated`, `transfer.completed`, `transfer.failed`, `transfer.updated`, `transfer.cancelled`, `transfer.reversed`, `external_account.in_review`, `external_account.approved`, `external_account.rejected`, `counterparty.created` — see [Webhooks](https://docs.infinite.net/guides/webhooks.md)

## Next steps

> [card] [Customers](https://docs.infinite.net/concepts/customers.md)
>
> Customer lifecycle and status

> [card] [Verification](https://docs.infinite.net/concepts/verification.md)
>
> Hosted links and API KYC / KYB

> [card] [Accounts](https://docs.infinite.net/concepts/accounts.md)
>
> Mailboxes, vaults, and external destinations

> [card] [Transfers](https://docs.infinite.net/concepts/transfers.md)
>
> Create and track payments

> [card] [Webhooks](https://docs.infinite.net/guides/webhooks.md)
>
> Lifecycle events

> [card] [Agents](https://docs.infinite.net/concepts/agents.md)
>
> Same objects for agent-initiated pay

> [card] [MCP](https://docs.infinite.net/guides/mcp.md)
>
> Hosted onboarding and platform Connect transfers from AI tools


## Related topics

- [Agents](https://docs.infinite.net/concepts/agents.md)
- [Infinite skill for AI assistants](https://docs.infinite.net/agent-skill.md)
- [MCP Server](https://docs.infinite.net/guides/mcp.md)
- [List mandates for a customer](https://docs.infinite.net/api-reference/mandates/list-mandates-for-a-customer.md)
- [Welcome](https://docs.infinite.net/welcome.md)