Set an account's settlement preference

Set account settlement preference

curl --request PUT \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "settlementDestinationId": "destination_123",
  "assetSymbol": "USDC"
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile"

payload = {
    "settlementDestinationId": "destination_123",
    "assetSymbol": "USDC"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({settlementDestinationId: 'destination_123', assetSymbol: 'USDC'})
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile', 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://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'settlementDestinationId' => 'destination_123',
    'assetSymbol' => 'USDC'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "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://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile"

	payload := strings.NewReader("{\n  \"settlementDestinationId\": \"destination_123\",\n  \"assetSymbol\": \"USDC\"\n}")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	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.put("https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"settlementDestinationId\": \"destination_123\",\n  \"assetSymbol\": \"USDC\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"settlementDestinationId\": \"destination_123\",\n  \"assetSymbol\": \"USDC\"\n}"

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

{
  "id": "settle_123",
  "accountId": "acct_123",
  "version": 2,
  "connectedWalletId": "wallet_123",
  "settlementDestinationId": "destination_123",
  "status": "active",
  "destinationType": "connected_wallet",
  "chainId": 42161,
  "destinationAddress": "0x1111111111111111111111111111111111111111",
  "assetSymbol": "USDC",
  "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "snapshot": {}
}

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

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The credential does not allow this operation"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The resource was not found"
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was already used with a different request"
  }
}

{
  "error": {
    "code": "chain_config_missing",
    "message": "The requested network is not configured for this environment"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

PUT

accounts

{accountId}

settlement-profile

Set account settlement preference

curl --request PUT \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "settlementDestinationId": "destination_123",
  "assetSymbol": "USDC"
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile"

payload = {
    "settlementDestinationId": "destination_123",
    "assetSymbol": "USDC"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({settlementDestinationId: 'destination_123', assetSymbol: 'USDC'})
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile', 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://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'settlementDestinationId' => 'destination_123',
    'assetSymbol' => 'USDC'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "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://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile"

	payload := strings.NewReader("{\n  \"settlementDestinationId\": \"destination_123\",\n  \"assetSymbol\": \"USDC\"\n}")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	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.put("https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"settlementDestinationId\": \"destination_123\",\n  \"assetSymbol\": \"USDC\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/accounts/{accountId}/settlement-profile")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"settlementDestinationId\": \"destination_123\",\n  \"assetSymbol\": \"USDC\"\n}"

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

{
  "id": "settle_123",
  "accountId": "acct_123",
  "version": 2,
  "connectedWalletId": "wallet_123",
  "settlementDestinationId": "destination_123",
  "status": "active",
  "destinationType": "connected_wallet",
  "chainId": 42161,
  "destinationAddress": "0x1111111111111111111111111111111111111111",
  "assetSymbol": "USDC",
  "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "snapshot": {}
}

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

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The credential does not allow this operation"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The resource was not found"
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was already used with a different request"
  }
}

{
  "error": {
    "code": "chain_config_missing",
    "message": "The requested network is not configured for this environment"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

Pass a settlementDestinationId returned by List an account’s settlement destinations, and optionally an assetSymbol. The destination must be an active crypto wallet destination. A destination that is not active returns 409, and bank and rail-identifier destinations cannot be selected. Repeating the same preference returns the existing profile. Deposits and Payments that already exist keep their immutable settlement snapshot. 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

Select an active typed settlement destination returned by the settlement-destinations endpoint. Native assets cannot be selected for token settlement. THBT is Movement-only. JPYC is Polygon-only. USDG is Robinhood Chain-only (4663).

settlementDestinationId

string

required

Use the ID returned by GET /v2/accounts/{accountId}/settlement-destinations.

Example:

"destination_123"

assetSymbol

enum<string>

Available options:

USDC,

USDT,

THBT,

JPYC,

USDG

Example:

"USDC"

Response

Settlement profile

string

required

Example:

"settle_123"

accountId

string

required

Example:

"acct_123"

version

integer

required

Required range: x >= 1

Example:

2

connectedWalletId

string | null

required

Example:

"wallet_123"

settlementDestinationId

string | null

required

Example:

"destination_123"

status

enum<string>

required

Available options:

draft,

active,

inactive,

failed

Example:

"active"

destinationType

enum<string>

required

Available options:

smart_wallet,

connected_wallet,

external_wallet

Example:

"connected_wallet"

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 can be used for deposits but not as a settlement destination.

Available options:

42161,

1,

8453,

137,

56,

43114,

4663,

4217,

10103,

10002

Example:

42161

destinationAddress

string

required

Example:

"0x1111111111111111111111111111111111111111"

assetSymbol

enum<string>

required

Available options:

USDC,

USDT,

THBT,

JPYC,

USDG

tokenAddress

string

required

Example:

"0xaf88d065e77c8cC2239327C5EDb3A432268e5831"

snapshot

object

required

createdAt

string<date-time>

updatedAt

string<date-time>

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Set an account's settlement preference

Authorizations

Headers

Path Parameters

Body

Response