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
