Create an account

curl --request POST \
  --url https://api-sandbox.circle.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "description": "My account",
  "type": "first_party",
  "purpose": "custody",
  "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/accounts"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "description": "My account",
    "type": "first_party",
    "purpose": "custody",
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    description: 'My account',
    type: 'first_party',
    purpose: 'custody',
    clientEntityId: 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  })
};

fetch('https://api-sandbox.circle.com/v1/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.circle.com/v1/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'description' => 'My account',
    'type' => 'first_party',
    'purpose' => 'custody',
    'clientEntityId' => 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.circle.com/v1/accounts"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "accountId": "1000662322",
    "entityId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
    "type": "first_party",
    "purpose": "custody",
    "status": "active",
    "description": "My account",
    "balances": [
      {
        "amount": "3.14",
        "currency": "USD"
      }
    ],
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
    "businessPii": {
      "businessName": "Acme Corporation",
      "businessUniqueIdentifier": "12-3456789",
      "identifierIssuingCountryCode": "US",
      "address": {
        "line1": "100 Pine Street",
        "city": "San Francisco",
        "postalCode": "94111",
        "country": "US",
        "line2": "Suite 2500",
        "district": "CA"
      }
    },
    "groupId": "9c0f1c0d-6c61-4f3d-9b8a-1a3a4b3c5d6e"
  }
}

{
  "code": 2,
  "message": "API parameter invalid."
}

{
  "code": 4,
  "message": "Unauthorized."
}

{
  "code": 409,
  "message": "Conflict."
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

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 a business entity that will settle stablecoin payments by the customer.

Routing for this endpoint is body based. Requests that include the businessPii field are routed to the Managed Payments intermediary account creation flow, while requests that omit the businessPii field are routed to the standard account creation flow.

Both flows require an explicit type and purpose in the request body:

Standard (digital asset / Mint) accounts use purpose custody and type first_party or third_party. When clientEntityId is omitted the account is owned by the caller and type must be first_party; when clientEntityId is provided the account is owned by a sub-entity and type must be third_party.
Managed Payments intermediary accounts use type first_party and purpose payments.

POST

accounts

Create an account

curl --request POST \
  --url https://api-sandbox.circle.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "description": "My account",
  "type": "first_party",
  "purpose": "custody",
  "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/accounts"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "description": "My account",
    "type": "first_party",
    "purpose": "custody",
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    description: 'My account',
    type: 'first_party',
    purpose: 'custody',
    clientEntityId: 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  })
};

fetch('https://api-sandbox.circle.com/v1/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.circle.com/v1/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'description' => 'My account',
    'type' => 'first_party',
    'purpose' => 'custody',
    'clientEntityId' => 'a3f1b2c4-d5e6-7890-abcd-ef1234567890'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.circle.com/v1/accounts"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"description\": \"My account\",\n  \"type\": \"first_party\",\n  \"purpose\": \"custody\",\n  \"clientEntityId\": \"a3f1b2c4-d5e6-7890-abcd-ef1234567890\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "accountId": "1000662322",
    "entityId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
    "type": "first_party",
    "purpose": "custody",
    "status": "active",
    "description": "My account",
    "balances": [
      {
        "amount": "3.14",
        "currency": "USD"
      }
    ],
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
    "businessPii": {
      "businessName": "Acme Corporation",
      "businessUniqueIdentifier": "12-3456789",
      "identifierIssuingCountryCode": "US",
      "address": {
        "line1": "100 Pine Street",
        "city": "San Francisco",
        "postalCode": "94111",
        "country": "US",
        "line2": "Suite 2500",
        "district": "CA"
      }
    },
    "groupId": "9c0f1c0d-6c61-4f3d-9b8a-1a3a4b3c5d6e"
  }
}

{
  "code": 2,
  "message": "API parameter invalid."
}

{
  "code": 4,
  "message": "Unauthorized."
}

{
  "code": 409,
  "message": "Conflict."
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Mint Account
Managed Payments Intermediary Account

Create a Mint account

idempotencyKey

string<uuid>

required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

description

string

required

Human-readable description of the account.

Example:

"My account"

type

enum<string>

required

External account type.

first_party: the calling entity itself owns the account.
third_party: a sub-entity or end user owns the account.

Available options:

first_party,

third_party

Example:

"first_party"

purpose

enum<string>

required

Intended use of the account. Digital asset (Mint) accounts always hold stablecoin balances for the owning entity, so the only supported value is custody.

Available options:

custody

Example:

"custody"

clientEntityId

string<uuid>

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.

Example:

"a3f1b2c4-d5e6-7890-abcd-ef1234567890"

Response

Successfully created an account.

data

object

An account returned by the create account endpoint.

Show child attributes

List all accounts

Get an account

⌘I

API overview

Fiat payouts

Managed Payments

Stablecoin payments

Create an account

Authorizations

Body

Response