Create an account
Creates a new account. This account can be used to create accounts for Mint, or intermediary accounts for a Managed Payments customer. For Managed Payments, the account created represents the end customer that will settle stablecoin payments by the customer. That end customer can be either a business or an individual (retail) end customer.
Routing for this endpoint is body based. Requests that include businessPii,
individualPii, or endCustomerType are routed to the Managed Payments
intermediary account creation flow, while requests that include none of those
fields are routed to the standard account creation flow.
For Managed Payments, endCustomerType selects which PII block is required:
business, or omitted, requiresbusinessPiiand rejectsindividualPii.individualrequiresindividualPiiand rejectsbusinessPii.
Both flows require an explicit type and purpose in the request body:
- Standard (digital asset / Mint) accounts use
purposecustodyandtypefirst_partyorthird_party. WhenclientEntityIdis omitted the account is owned by the caller andtypemust befirst_party; whenclientEntityIdis provided the account is owned by a sub-entity andtypemust bethird_party. - Managed Payments intermediary accounts use
typefirst_partyandpurposepayments.
To create a non-custodial account for an end customer, send
custodyType self, type third_party, purpose custody, and the end
user’s clientEntityId. blockchain is optional and defaults to ARC. The
request must carry an X-Device-Authorization header from an authorization key the
end user registered through
POST /v1/accounts/auth/deviceKeyRegistration. The Digital Asset Accounts SDK builds and signs
this request, and your backend relay forwards it unchanged. The account is
created with status pending; get the account until its status is
active or rejected.
To retry after a timeout or a lost response, resend the request with the
same idempotencyKey; Circle returns the account it already created. A new
account (a new idempotencyKey) needs a new X-Device-Authorization
value; reusing one that already created an account returns 409 (error
code 420043).
Requests without custodyType create a custodial account as described above.
Authorizations
Headers
Compact ES256 JWS that the Digital Asset Accounts SDK creates on the end user's device. It signs this request's method, path, and exact body bytes with the authorization key the end user registered. The SDK creates a new value for every call. To retry a request, resend the original body and header unchanged when you can. Operations where a retry with a new header returns 409 (error code 420034) explain in that response how to find the original request.
Required when the request acts on a non-custodial account (custodyType self), and not used for other accounts. A missing value on a non-custodial request returns 400 (error code 420031). A value that isn't a well-formed compact JWS returns 401 (error code 420031) on any account.
The SDK gives each value an expiry at most 5 minutes after it signs it. Circle rejects a value whose expiry has passed or whose signing time is in the future, allowing 60 seconds of clock difference either way, with 400 (error code 420031). A device clock that's off by more than 60 seconds causes the same error. Retry within the value's lifetime, or let the SDK sign the request again.
Your backend relay must forward this header, and the request body, exactly as the SDK sent them. Don't parse, reformat, or re-serialize the body. If the bytes change, Circle rejects the request.
Compact ES256 JWS created by the Digital Asset Accounts SDK on the end user's device.
64 - 8192"eyJhbGciOiJFUzI1NiJ9.e30.AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-Pw"
Body
- Mint Account
- Managed Payments Intermediary Account (Business)
- Managed Payments Intermediary Account (Individual)
- Non-Custodial Account
Create a Mint account
Optional identifier of the client entity whose account should be created. If omitted, the account is owned by the caller and type must be first_party. If provided, the account is owned by a sub-entity and type must be third_party.
"a3f1b2c4-d5e6-7890-abcd-ef1234567890"