Institutional API

Understand how the Institutional API lets Circle Mint distributors mint, redeem, and transfer on behalf of compliance-screened external entities with their own per-entity wallets.

The Institutional API is for Circle Mint customers with the institutional entitlement (Distributors) who operate fiat-to-stablecoin flows on behalf of their own institutional end clients. It lets you onboard those end clients as external entities, screen them through Circle compliance, and then mint, redeem, and transfer USDC on their behalf. Each entity gets its own dedicated wallet so balances and money movement stay segregated by counterparty.

Why use the Institutional API

Without the Institutional API, every counterparty that needs to mint or redeem through Circle would have to onboard as a direct Circle Mint customer. The Institutional API solves that by letting one Distributor’s Mint account act as the integration surface for many institutional end clients. Circle still runs compliance on each external entity, but the Distributor—not the end client— holds the API key and runs the integration.

The API is intended for B2B2B Distributors servicing institutional end clients, such as:

• Commercial banks
• Institutional banks
• Centralized exchanges
• Custodians
• TradFi trading platforms
• Real-world asset (RWA) platforms

Retail-only use cases and internal-only flows do not require the Institutional API.

Distributor and external entity

The Institutional API revolves around two roles. The Distributor is the Circle Mint customer; the external entity is the Distributor’s institutional end client. Each role has a different relationship to Circle and to the API.

Aspect	Distributor	External entity
Role	The Circle Mint customer integrating the Institutional API.	The Distributor’s institutional end client.
API access	Holds the API key and authenticates all requests.	Never accesses the Circle Mint API directly.
Wallet	Owns a primary wallet identified by masterWalletId, used as the default source and destination when no entity wallet is specified.	Receives a dedicated subaccount wallet (type end_user_wallet) after Circle accepts the entity in compliance.
Identity	Calls POST /v1/externalEntities to onboard each external entity.	Identified by businessName, businessUniqueIdentifier (tax ID), identifierIssuingCountryCode, and address submitted by the Distributor.
Money movement	Initiates mints, redemptions, and onchain transfers on behalf of each accepted entity.	Funds flow through the entity’s walletId; the entity itself does not call Circle APIs.

Compliance lifecycle

Every call to POST /v1/externalEntities triggers a synchronous sanctions screening on the entity’s business name, tax ID (businessUniqueIdentifier), issuing country code, and address. The 201 response returns the entity in complianceState: PENDING along with the provisioned walletId. The final decision—ACCEPTED or REJECTED—is delivered asynchronously through the externalEntities webhook topic.

The walletId is returned at creation but is unusable while the entity remains in PENDING or REJECTED. Wait for the externalEntities webhook to deliver complianceState: ACCEPTED before referencing the entity’s wallet in any other endpoint.

Per-entity wallet model

When Circle accepts an external entity, it provisions a dedicated wallet of type end_user_wallet and surfaces the wallet identifier as walletId (for example, "212000"). The wallet is owned by the Distributor’s Mint account but segregated to that entity, so balances and money movement remain attributable per counterparty.

Every relevant Mint endpoint accepts the entity’s walletId:

• On GET endpoints (such as listing deposits, payouts, or transfers), pass the entity wallet as the walletId query parameter: ?walletId=212000.
• On POST endpoints (such as creating a payout or an onchain transfer), pass the entity wallet in the request body as "source": { "type": "wallet", "id": "212000" }.

If walletId is omitted on a request, Circle defaults to the Distributor’s primary wallet (masterWalletId). The primary wallet remains available for the Distributor’s own balances and money movement; the entity wallets sit alongside it as siblings, not as children of the primary wallet.

Operational flows

The Institutional API supports three flows on behalf of an accepted external entity: minting, redeeming, and onchain transfer. The table below summarizes each flow at a conceptual level. For endpoint-level steps, see Manage institutional subaccounts.

Flow	What it does	Where the entity wallet appears
Mint on behalf of an entity	The end client wires fiat against entity-scoped wire instructions; Circle credits the entity wallet and fires a deposits webhook.	walletId query parameter on the wire-instructions request.
Redeem on behalf of an entity	The Distributor submits a payout from the entity wallet. The Institutional Direct fee is deducted at redemption, so toAmount reflects the net amount the entity’s bank receives.	source.id in the payout request body.
Onchain transfer on behalf of an entity	Outbound transfers draw from the entity wallet and target a verified destination from the Distributor’s address book; inbound transfers use a per-entity deposit address.	walletId query parameter on deposit-address requests; source.id in the transfer request body.

Billing

Institutional Direct is the default billing model for the Institutional API. A gross flat fee is applied to every redemption, charged to the end client at the point of redemption and deducted from the toAmount returned on the payout response. The Distributor sees the net amount in the payout payload, and the entity’s bank receives that net amount.

Alternative billing models are available by exception. Contact Circle to arrange one outside the API.

What is not supported

The Institutional API does not support the following operations on behalf of an external entity:

• Editing or deleting an external entity once it is created. Contact Circle to make changes.
• Express routes from entity subaccount wallets.
• Local-currency onramp flows (such as BRL, MXN, or EURC swaps) on behalf of entity subaccounts.
• Stablecoin Payins and Stablecoin Payouts against entity wallets.
• Cross-Currency Exchange against entity wallets.
• Credit API operations on behalf of an external entity.

See also

• Manage institutional subaccounts
• Webhook notifications: externalEntities