Set an account's payment source

curl --request PUT \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/payment-source \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "connected_wallet",
  "connectedWalletId": "wallet_123",
  "assetSymbol": "USDC"
}
'

{
  "id": "source_123",
  "accountId": "acct_123",
  "version": 1,
  "type": "connected_wallet",
  "chainId": 42161,
  "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "sourceAddress": "0xdFD4ab80E163D6864E26F37540563cBf2E52A582",
  "sourceRef": "wallet_123",
  "assetSymbol": "USDC",
  "status": "active"
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

PUT

accounts

{accountId}

payment-source

curl --request PUT \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/payment-source \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "connected_wallet",
  "connectedWalletId": "wallet_123",
  "assetSymbol": "USDC"
}
'

{
  "id": "source_123",
  "accountId": "acct_123",
  "version": 1,
  "type": "connected_wallet",
  "chainId": 42161,
  "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "sourceAddress": "0xdFD4ab80E163D6864E26F37540563cBf2E52A582",
  "sourceRef": "wallet_123",
  "assetSymbol": "USDC",
  "status": "active"
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

The payment source controls where outgoing Payments spend from; the settlement preference controls where incoming money lands. Choose one type:

`type`	Requirement
`connected_wallet`	`connectedWalletId` of a wallet already linked to the account.
`vault`	`vaultId` of the account’s active Stableyard Vault with an active policy. Vault sources currently support only the Vault policy assets (`USDC`, `USDT`) on Arbitrum. Enabled Vault routing can deliver to a different supported chain or token.

Vault sends need no per-send wallet signature, but every execution still passes policy, token, spend-window and mandate checks. Payment creation has no funding-source override, so Payments always use this account default. Repeating the same source returns the existing active preference. See Sending payments.

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

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

Path Parameters

accountId

string

required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Body

application/json

Connected wallet source
Vault source

type

string

required

Allowed value: "connected_wallet"

connectedWalletId

string

required

Must belong to the account.

Example:

"wallet_123"

assetSymbol

enum<string>

Available options:

USDC,

USDT,

THBT,

JPYC,

USDG

Example:

"USDC"

Response

Payment source

string

required

Example:

"source_123"

accountId

string

required

Example:

"acct_123"

version

integer

required

Required range: x >= 1

Example:

1

type

enum<string>

required

Available options:

connected_wallet,

vault

chainId

enum<integer>

required

Supported settlement chain IDs: Arbitrum=42161, Ethereum=1, Base=8453, Polygon=137, BNB Smart Chain=56, Avalanche=43114, Robinhood Chain=4663, Tempo=4217, Solana=10103, Movement=10002. Settlement currently supports EVM, Solana, and Movement token destinations. Movement also supports THBT, while Polygon supports direct same-chain JPYC settlement. Tron is deposit-only for settlement-fee escrow.

Available options:

42161,

1,

8453,

137,

56,

43114,

4663,

4217,

10103,

10002

tokenAddress

string

required

Example:

"0xaf88d065e77c8cC2239327C5EDb3A432268e5831"

assetSymbol

enum<string>

required

Available options:

USDC,

USDT,

THBT,

JPYC,

USDG

Example:

"USDC"

status

enum<string>

required

Available options:

active,

disabled

sourceAddress

string | null

Example:

"0xdFD4ab80E163D6864E26F37540563cBf2E52A582"

sourceRef

string | null

Example:

"wallet_123"

createdAt

string<date-time>

updatedAt

string<date-time>

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Set an account's payment source

Authorizations

Headers

Path Parameters

Body

Response