> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}. > Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts. > Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md. > Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md. > Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers. > Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews. > Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming. > Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md. > Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors. > API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product. > Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes. > When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records. > Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md. # Manage institutional subaccounts > Step-by-step guide for Circle Mint distributors to create external entities, mint and redeem on their behalf, transfer USDC onchain, and query entity-scoped activity. Operate fiat-to-stablecoin flows on behalf of an external entity end-to-end: onboard the entity, wait for the compliance decision, then mint, redeem, and transfer USDC onchain on its behalf using the entity's dedicated `walletId`. Use this guide when you hold the Institutional API entitlement as a Distributor and you're integrating a new institutional counterparty into your Circle Mint account. For the conceptual model, see [Institutional API](/circle-mint/concepts/institutional-api). ## Prerequisites Before you begin, ensure that you've: * Confirmed the Institutional API entitlement is enabled on your Circle Mint account. [Contact Circle](https://www.circle.com/mint-contact) if you don't see it. * Created an API key with institutional permissions. * Set up a webhook subscription that includes the `externalEntities`, `deposits`, `transfers`, and `payouts` topics. See [Set up a webhook endpoint](/api-reference/webhook-endpoints#v1-notifications). * Verified at least one linked bank account for receiving wires from your end client. See [Depositing Fiat](/circle-mint/howtos/deposit-fiat). * Reviewed the conceptual model in [Institutional API](/circle-mint/concepts/institutional-api). ## Step 1: Create an external entity Call `POST /v1/externalEntities` with the entity's `businessName`, `businessUniqueIdentifier` (tax ID), `identifierIssuingCountryCode`, and `address`. ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/externalEntities \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "businessName": "Acme Treasury Ltd.", "businessUniqueIdentifier": "12-3456789", "identifierIssuingCountryCode": "US", "address": { "line1": "100 Market St", "city": "San Francisco", "district": "CA", "postalCode": "94105", "country": "US" } }' ``` The response returns HTTP 201 with `complianceState: PENDING`: ```json theme={null} { "data": { "walletId": "212000", "businessName": "Acme Treasury Ltd.", "businessUniqueIdentifier": "12-3456789", "identifierIssuingCountryCode": "US", "complianceState": "PENDING" } } ``` The `walletId` is returned at creation but remains unusable while the entity is in `PENDING` or `REJECTED`. Wait for the compliance decision before referencing the entity's wallet in any other endpoint. ## Step 2: Wait for the compliance decision Subscribe to the `externalEntities` webhook topic to receive the asynchronous compliance decision. On `ACCEPTED`, the payload confirms the entity's `walletId` is usable. On `REJECTED`, the entity cannot be used: resubmit a new entity with corrected information or [contact Circle](https://www.circle.com/mint-contact). As a fallback, poll `GET /v1/externalEntities/{walletId}` with the `walletId` returned at creation until `complianceState` changes. ```json theme={null} { "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802", "notificationType": "externalEntities", "version": 1, "externalEntity": { "walletId": "212000", "businessName": "Acme Treasury Ltd.", "businessUniqueIdentifier": "12-3456789", "identifierIssuingCountryCode": "US", "complianceState": "ACCEPTED" } } ``` ## Step 3: Mint on behalf of the entity Use the entity's `walletId` to scope wire instructions, then watch for the deposit to land on the entity wallet. ### 3.1. Generate entity-scoped wire instructions Call `GET /v1/businessAccount/banks/wires/{id}/instructions?walletId=`, passing the linked bank `id` in the path and the entity wallet in the query string. ```bash theme={null} curl "https://api-sandbox.circle.com/v1/businessAccount/banks/wires/9d1fa351-b24d-442a-8aa5-e717db1ed636/instructions?walletId=212000" \ -H "Authorization: Bearer $API_KEY" ``` The response returns the entity-scoped `trackingRef`; deposits that include it are credited to the entity wallet: ```json theme={null} { "data": { "trackingRef": "CIR22FEP33", "beneficiary": { "name": "CIRCLE INTERNET FINANCIAL INC", "address1": "1 MAIN STREET", "address2": "SUITE 1" }, "virtualAccountEnabled": true, "beneficiaryBank": { "name": "CRYPTO BANK", "address": "1 MONEY STREET", "city": "NEW YORK", "postalCode": "1001", "country": "US", "swiftCode": "CRYPTO99", "routingNumber": "999999999", "accountNumber": "123815146304", "currency": "USD" } } } ``` ### 3.2. Have the end client wire fiat to those instructions Share the beneficiary details and the entity-scoped `trackingRef` with your end client. Optionally include a `customerExternalRef` matching `.*(EXT[A-Z0-9]{18}).*` in the bank memo for Distributor-side reconciliation. ### 3.3. Watch the `deposits` webhook for the credit Circle fires a `deposits` event with `destination.id` equal to the entity's `walletId` once the wire settles. The USDC or EURC is then available in the entity wallet. ```json theme={null} { "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802", "notificationType": "deposits", "version": 1, "deposit": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "sourceWalletId": "212000", "destination": { "type": "wallet", "id": "212000" }, "amount": { "amount": "50000.00", "currency": "USD" }, "status": "complete", "trackingRef": "CIR22FEP33", "createDate": "2026-05-01T14:20:30.000Z", "updateDate": "2026-05-01T14:21:12.000Z" } } ``` ## Step 4: Transfer USDC onchain on behalf of the entity Move USDC into or out of the entity wallet onchain by scoping the deposit address and the transfer source to the entity `walletId`. ### 4.1. Generate an entity-scoped deposit address for inbound transfers Call `POST /v1/businessAccount/wallets/addresses/deposit` with the entity wallet in the request body. Mint supports the same blockchains for institutional subaccount wallets as for the Distributor's primary wallet. See [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies). ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/deposit \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "walletId": "212000", "currency": "USD", "chain": "ARC" }' ``` ### 4.2. Send an outbound transfer from the entity wallet First, allowlist the recipient with `POST /v1/businessAccount/wallets/addresses/recipient`. The address must be approved by an account administrator through the Mint Console before it can be used. Watch the [`addressBookRecipients`](/circle-mint/references/webhook-notifications#addressbookrecipients) webhook for the `active` status that signals approval. Then create the transfer with `POST /v1/businessAccount/transfers`, setting `source.type` to `wallet` and `source.id` to the entity's `walletId`. ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/businessAccount/transfers \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": { "type": "wallet", "id": "212000" }, "destination": { "type": "verified_blockchain", "addressId": "addr_01HZ..." }, "amount": { "amount": "1000.00", "currency": "USD" }, "idempotencyKey": "9352ec9e-5ee6-441f-ab42-186bc71fbdde" }' ``` ## Step 5: Redeem on behalf of the entity Call `POST /v1/businessAccount/payouts` with `source.type` set to `wallet`, `source.id` set to the entity's `walletId`, and `destination.type` set to `wire` with the linked fiat account `id`. Watch the `payouts` webhook for `complete` or `failed`. ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/businessAccount/payouts \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": { "type": "wallet", "id": "212000" }, "destination": { "type": "wire", "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636" }, "amount": { "amount": "10000.00", "currency": "USD" }, "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7" }' ``` The Institutional Direct fee is deducted at the point of redemption, so the `toAmount` returned on the payout reflects the net amount the entity's bank receives: ```json theme={null} { "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802", "notificationType": "payouts", "version": 1, "payout": { "id": "c0f88a17-2a8b-4d51-9c4e-c8d3f2cfa011", "sourceWalletId": "212000", "destination": { "type": "wire", "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636" }, "amount": { "amount": "10000.00", "currency": "USD" }, "toAmount": { "amount": "9990.00", "currency": "USD" }, "fees": { "amount": "10.00", "currency": "USD" }, "status": "complete", "createDate": "2026-05-01T14:20:30.000Z", "updateDate": "2026-05-01T14:25:11.000Z" } } ``` ## Step 6: Query entity-scoped activity Filter list endpoints by the entity's `walletId` (or `sourceWalletId` / `destinationWalletId` where supported) to retrieve activity scoped to a single entity: * Balance: `GET /v1/businessAccount/balances?walletId=` * Deposits: `GET /v1/businessAccount/deposits?walletId=` * Transfers: `GET /v1/businessAccount/transfers?walletId=`. Use `sourceWalletId` or `destinationWalletId` to filter by direction. * Payouts: `GET /v1/businessAccount/payouts?sourceWalletId=` * Deposit addresses: `GET /v1/businessAccount/wallets/addresses/deposit?walletId=` Omitting `walletId` on these endpoints returns activity for the Distributor's primary wallet (`masterWalletId`), not all entities. Always pass the entity `walletId` when you want entity-scoped results. ## Endpoint reference The following table maps each operation in this guide to its endpoint and the location of the `walletId` parameter. | Operation | Method and path | `walletId` location | | - | - | - | | Create external entity | `POST /v1/externalEntities` | Body | | List external entities | `GET /v1/externalEntities` | Optional filter via `businessUniqueIdentifier` | | Get external entity | `GET /v1/externalEntities/{walletId}` | Path parameter | | Get entity wire instructions | `GET /v1/businessAccount/banks/wires/{id}/instructions?walletId=…` | Query string | | Generate entity deposit address | `POST /v1/businessAccount/wallets/addresses/deposit` | Body (`walletId`) | | List entity deposit addresses | `GET /v1/businessAccount/wallets/addresses/deposit?walletId=…` | Query string | | Transfer onchain from entity | `POST /v1/businessAccount/transfers` | Body (`source.id` with `source.type: wallet`) | | List entity transfers | `GET /v1/businessAccount/transfers?walletId=…` | Query string | | Redeem from entity | `POST /v1/businessAccount/payouts` | Body (`source.id` with `source.type: wallet`) | | List entity payouts | `GET /v1/businessAccount/payouts?sourceWalletId=…` | Query string | | List entity deposits | `GET /v1/businessAccount/deposits?walletId=…` | Query string | | Entity balance | `GET /v1/businessAccount/balances?walletId=…` | Query string | ## See also * [Institutional API](/circle-mint/concepts/institutional-api): conceptual model for Distributors, external entities, and per-entity wallets. * [Webhook notifications](/circle-mint/references/webhook-notifications#externalentities): schema and delivery for the `externalEntities` callback. * [Error codes](/api-reference/circle-mint/error-codes): synchronous and asynchronous failure modes. * [Supported payment rails](/circle-mint/references/supported-payment-rails): fiat rails available for entity wire deposits and redemptions. * [Depositing Fiat](/circle-mint/howtos/deposit-fiat): linked bank account setup and wire deposit basics.