Skip to main content
POST
Link wallet to UPA
When the account has no settlement wallet or settlement profile yet, the first settlement-supported wallet you link becomes its preferred settlement wallet. Otherwise, linking wallets leaves settlement unchanged unless you mark one wallet isPreferredSettlement: true. Linked wallets appear as crypto destinations in List an account’s settlement destinations. See Settlement destinations.

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
wallets
object[]
required

Wallets to link. For a wallet-less account without a settlement profile, the first settlement-supported wallet becomes settlement. Otherwise, linking wallets does not change settlement unless one wallet is marked isPreferredSettlement.

Minimum array length: 1

Response

Connected wallets

id
string
required
Example:

"wallet_123"

accountId
string
required
Example:

"acct_123"

kind
enum<string>
required
Available options:
evm,
tron,
solana,
movement
chainId
enum<integer>
required

Supported connected-wallet 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, Tron=728126428. Address family must match the selected chain ID.

Available options:
42161,
1,
8453,
137,
56,
43114,
4663,
4217,
10103,
10002,
728126428
Example:

42161

address
string
required

Wallet address. EVM addresses are normalized to lowercase before storage; other address families retain their submitted casing.

Example:

"0x1111111111111111111111111111111111111111"

status
enum<string>
required

Whether this wallet link can be used by the account.

Available options:
active,
disabled
ownershipVerificationStatus
enum<string>
required

Ownership is unverified until Stableyard records a successful proof. Linking a wallet alone never verifies ownership.

Available options:
unverified,
verified
settlementProfileId
string | null
required

The active settlement profile id when this wallet is the account settlement wallet; otherwise null.

Example:

"settle_123"

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
label
string | null
Example:

"Connected wallet"

ownershipVerificationMethod
string | null
Example:

"eip712_signature"

ownershipVerifiedAt
string<date-time> | null