Create an account

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "externalUserId": "user_123",
  "subjectType": "individual",
  "handle": "alice",
  "wallets": [
    {
      "address": "0x1111111111111111111111111111111111111111",
      "chainId": 8453,
      "label": "User wallet on Base"
    },
    {
      "address": "0x2222222222222222222222222222222222222222",
      "chainId": 42161,
      "label": "User wallet on Arbitrum",
      "isPreferredSettlement": true
    }
  ]
}
'

{
  "account": {
    "id": "acct_123",
    "externalUserId": "user_123",
    "subjectType": "individual",
    "status": "active",
    "paymentAcceptance": {
      "publicReceiveEnabled": false,
      "version": 1
    },
    "metadata": {},
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "paymentHandle": {
    "id": "handle_123",
    "accountId": "acct_123",
    "namespace": "partner",
    "handle": "alice",
    "status": "active",
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "connectedWallets": [
    {
      "id": "wallet_123",
      "accountId": "acct_123",
      "kind": "evm",
      "chainId": 42161,
      "address": "0x1111111111111111111111111111111111111111",
      "label": "Connected wallet",
      "status": "active",
      "ownershipVerificationStatus": "unverified",
      "ownershipVerificationMethod": "eip712_signature",
      "settlementProfileId": "settle_123",
      "createdAt": "2026-08-28T10:00:00.000Z",
      "updatedAt": "2026-08-28T10:00:00.000Z"
    }
  ],
  "settlementProfile": {
    "id": "settle_123",
    "accountId": "acct_123",
    "version": 2,
    "connectedWalletId": "wallet_123",
    "settlementDestinationId": "destination_123",
    "status": "draft",
    "destinationType": "smart_wallet",
    "chainId": 42161,
    "destinationAddress": "11111111111111111111111111111111",
    "assetSymbol": "USDC",
    "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "snapshot": {}
  }
}

POST

accounts

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "externalUserId": "user_123",
  "subjectType": "individual",
  "handle": "alice",
  "wallets": [
    {
      "address": "0x1111111111111111111111111111111111111111",
      "chainId": 8453,
      "label": "User wallet on Base"
    },
    {
      "address": "0x2222222222222222222222222222222222222222",
      "chainId": 42161,
      "label": "User wallet on Arbitrum",
      "isPreferredSettlement": true
    }
  ]
}
'

{
  "account": {
    "id": "acct_123",
    "externalUserId": "user_123",
    "subjectType": "individual",
    "status": "active",
    "paymentAcceptance": {
      "publicReceiveEnabled": false,
      "version": 1
    },
    "metadata": {},
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "paymentHandle": {
    "id": "handle_123",
    "accountId": "acct_123",
    "namespace": "partner",
    "handle": "alice",
    "status": "active",
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "connectedWallets": [
    {
      "id": "wallet_123",
      "accountId": "acct_123",
      "kind": "evm",
      "chainId": 42161,
      "address": "0x1111111111111111111111111111111111111111",
      "label": "Connected wallet",
      "status": "active",
      "ownershipVerificationStatus": "unverified",
      "ownershipVerificationMethod": "eip712_signature",
      "settlementProfileId": "settle_123",
      "createdAt": "2026-08-28T10:00:00.000Z",
      "updatedAt": "2026-08-28T10:00:00.000Z"
    }
  ],
  "settlementProfile": {
    "id": "settle_123",
    "accountId": "acct_123",
    "version": 2,
    "connectedWalletId": "wallet_123",
    "settlementDestinationId": "destination_123",
    "status": "draft",
    "destinationType": "smart_wallet",
    "chainId": 42161,
    "destinationAddress": "11111111111111111111111111111111",
    "assetSymbol": "USDC",
    "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "snapshot": {}
  }
}

Pass your own stable externalUserId and the subject’s legal classification in subjectType (individual or business). Stableyard returns the canonical account.id that every account-scoped endpoint uses. Classify the real subject the UPA represents, not the owner of a connected wallet. You can also pass initial wallets, a handle and an email. If you send wallets and none is marked isPreferredSettlement, the first settlement-supported wallet becomes the settlement wallet. Sending email with emailVerified is equivalent to calling Verify or link an account email right after creation: emailVerified: true asserts you already verified the address and requires partner-asserted verification to be enabled for the app environment, while false starts Stableyard’s own OTP flow. The call is create-only: an externalUserId that already has a UPA returns 409 account_already_exists. Idempotency-Key is required. Retrying with the same key and identical input returns the original account; different input returns 409 idempotency_conflict. Change wallets, settlement and the handle later through their dedicated endpoints. See Universal Payment Account for what the account controls.

Authorizations

Authorization

string

header

required

HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.

Headers

Idempotency-Key

string

required

Required retry key for account creation. Reusing the same key with identical input returns the original account; reusing it with different input returns 409 idempotency_conflict.

Required string length: 1 - 256

Pattern: ^[ -~]+$

Example:

"account-user-123-v1"

Stableyard-Version

enum<string>

Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.

Available options:

2026-09-09

Body

application/json

externalUserId

string

required

Stable partner-owned identifier. Unicode control characters are rejected.

Maximum string length: 128

Example:

"user_123"

subjectType

enum<string>

required

Required legal classification of the UPA subject. This is explicit and is never inferred from identifiers, wallets, metadata, or payment behavior.

Available options:

individual,

business

Example:

"individual"

handle

string

Maximum string length: 105

Example:

"alice"

displayProfile

object

Optional payer-facing recipient identity. It is separate from app branding and can be updated later with the versioned display-profile endpoint.

Show child attributes

wallets

object[]

Optional connected wallets to link during account creation. If one settlement-supported wallet is sent, it becomes settlement. If multiple wallets are sent, mark one with isPreferredSettlement; otherwise the first settlement-supported wallet becomes settlement.

Minimum array length: 1

Show child attributes

string<email>

Optional UPA email, linked during account creation. Requires emailVerified.

Maximum string length: 320

Example:

"[email protected]"

emailVerified

boolean

Set with email. true asserts you already verified this address yourself, using the same partner_asserted contract as POST /accounts/{id}/email/verification-challenges — Stableyard trusts the assertion without sending its own OTP, and only if partner-asserted verification is enabled for this app environment. false or omitted starts Stableyard's own OTP flow to that address.

Example:

true

metadata

object

Optional partner metadata. Must be JSON-safe, at most 4096 bytes, depth 3, 25 keys per object, 512 characters per string, and 50 items per array.

Response

UPA created, or the original result of an identical idempotent retry

account

object

required

Show child attributes

connectedWallets

object[]

required

Show child attributes

paymentHandle

object

Show child attributes

settlementProfile

object

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Authorizations

Headers

Body

Response