POST
/
accounts
Create account.
curl --request POST \
  --url https://sandbox.api.openfx.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "customerId": "cus_01953e1a5f4b7000",
  "type": "demand_deposit",
  "currency": "USD",
  "label": "USD Operating Account"
}
'
{
  "id": "acc_01953e1a5f4b7002",
  "customerId": "cus_01953e1a5f4b7000",
  "type": "demand_deposit",
  "status": "active",
  "currency": "USD",
  "label": "USD Operating Account",
  "metadata": {},
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T12:00:00Z"
}

Authorizations

​
Authorization
string
header
required

API key issued at onboarding. Passed as a Bearer token in the Authorization header: Authorization: Bearer <api-key>. Identifies the caller and determines organization scope. Invalid or revoked keys return 401 with error type authentication_error.

​
X-Signature
string
header
required

Ed25519 or RSA-SHA256 asymmetric signature over the request payload (ADR-0015). Provides request integrity and non-repudiation. The signature covers the HTTP method, path, query string, request body, and timestamp. Invalid signatures return 401 with error type authentication_error.

​
X-Timestamp
string
header
required

Unix timestamp (seconds) of when the request was signed. Server rejects requests where the timestamp drifts beyond +/-60 seconds from server time to prevent replay attacks. Must match the timestamp used in the signature computation.

Headers

​
Idempotency-Key
string
required

Idempotency key for this request. UUID v4 recommended. Max 128 characters. 24-hour retention. Same key + same body replays original response with Idempotency-Replayed: true. Same key + different body returns 409 (code: duplicate_idempotency_key). Same key while the original request is still processing returns 409 with a Retry-After header (code: idempotency_key_in_flight).

Maximum string length: 128
Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Request body for creating an account. The type field determines whether this is a fiat account (demand_deposit or virtual) or a crypto wallet account (wallet).

​
customerId
string
required

Customer resource identifier.

Pattern: ^cus_[A-Za-z0-9]+$
Example:

"cus_01953e1a5f4b7000"

​
type
enum<string>
required

Account type. Use demand_deposit for standard fiat bank accounts or virtual for segregated sub-accounts.

Available options:
demand_deposit,
virtual
​
currency
string
required

ISO 4217 currency code for the fiat account.

Pattern: ^[A-Z]{2,10}$
Example:

"USD"

​
label
string

Consumer-defined label for the account.

​
purpose
enum<string>

Intended purpose of this account. Used for compliance classification.

Available options:
operating,
payroll,
vendor_payments,
treasury,
collections,
disbursement,
escrow,
other
​
metadata
object

Consumer-defined key-value store. Available on all primary resources. Max 50 keys. Keys must match ^[a-zA-Z0-9_]{1,40}$. Values are strings (max 500 chars) or null.

Response

Account created.

Unified ledger account for fiat and crypto assets. Replaces the V2 separation of /accounts and /wallets. The type field distinguishes demand_deposit (fiat), wallet (crypto), and virtual accounts. Use the type discriminator to determine which variant applies.

​
id
string
required

Account resource identifier.

Pattern: ^acc_[A-Za-z0-9]+$
Example:

"acc_01953e1a5f4b7002"

​
customerId
string
required

Customer resource identifier.

Pattern: ^cus_[A-Za-z0-9]+$
Example:

"cus_01953e1a5f4b7000"

​
type
enum<string>
required

Account type. demand_deposit for standard fiat bank accounts, virtual for segregated sub-accounts.

Available options:
demand_deposit,
virtual
​
status
enum<string>
required

Lifecycle status of an account.

Available options:
pending,
active,
suspended,
closed
​
createdAt
string<date-time>
required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

​
updatedAt
string<date-time>
required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

​
currency
string
required

ISO 4217 currency code for the fiat account.

Pattern: ^[A-Z]{2,10}$
Example:

"USD"

​
label
string

Consumer-defined label for the account.

Example:

"Operating Account - USD"

​
purpose
enum<string>

Intended purpose of this account. Used for compliance classification.

Available options:
operating,
payroll,
vendor_payments,
treasury,
collections,
disbursement,
escrow,
other
​
metadata
object

Consumer-defined key-value store. Available on all primary resources. Max 50 keys. Keys must match ^[a-zA-Z0-9_]{1,40}$. Values are strings (max 500 chars) or null.