Issue an on-ramp bank account

Issue a persistent on-ramp bank account (US)

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/onramp-bank-accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "connectedWalletId": "wallet_abc123",
  "destinationAssetCode": "USDC",
  "rail": "ach",
  "recipientType": "individual",
  "recipientName": "Example account",
  "recipientAddress": {
    "street1": "example",
    "street2": "example",
    "street3": "example",
    "city": "example",
    "region": "example",
    "postalCode": "example",
    "country": "US"
  }
}
'

import requests

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

payload = {
    "connectedWalletId": "wallet_abc123",
    "destinationAssetCode": "USDC",
    "rail": "ach",
    "recipientType": "individual",
    "recipientName": "Example account",
    "recipientAddress": {
        "street1": "example",
        "street2": "example",
        "street3": "example",
        "city": "example",
        "region": "example",
        "postalCode": "example",
        "country": "US"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    connectedWalletId: 'wallet_abc123',
    destinationAssetCode: 'USDC',
    rail: 'ach',
    recipientType: 'individual',
    recipientName: 'Example account',
    recipientAddress: {
      street1: 'example',
      street2: 'example',
      street3: 'example',
      city: 'example',
      region: 'example',
      postalCode: 'example',
      country: 'US'
    }
  })
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/onramp-bank-accounts', 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}/onramp-bank-accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'connectedWalletId' => 'wallet_abc123',
    'destinationAssetCode' => 'USDC',
    'rail' => 'ach',
    'recipientType' => 'individual',
    'recipientName' => 'Example account',
    'recipientAddress' => [
        'street1' => 'example',
        'street2' => 'example',
        'street3' => 'example',
        'city' => 'example',
        'region' => 'example',
        'postalCode' => 'example',
        'country' => 'US'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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}/onramp-bank-accounts"

	payload := strings.NewReader("{\n  \"connectedWalletId\": \"wallet_abc123\",\n  \"destinationAssetCode\": \"USDC\",\n  \"rail\": \"ach\",\n  \"recipientType\": \"individual\",\n  \"recipientName\": \"Example account\",\n  \"recipientAddress\": {\n    \"street1\": \"example\",\n    \"street2\": \"example\",\n    \"street3\": \"example\",\n    \"city\": \"example\",\n    \"region\": \"example\",\n    \"postalCode\": \"example\",\n    \"country\": \"US\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.post("https://prod-api.stableyard.fi/v2/accounts/{accountId}/onramp-bank-accounts")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connectedWalletId\": \"wallet_abc123\",\n  \"destinationAssetCode\": \"USDC\",\n  \"rail\": \"ach\",\n  \"recipientType\": \"individual\",\n  \"recipientName\": \"Example account\",\n  \"recipientAddress\": {\n    \"street1\": \"example\",\n    \"street2\": \"example\",\n    \"street3\": \"example\",\n    \"city\": \"example\",\n    \"region\": \"example\",\n    \"postalCode\": \"example\",\n    \"country\": \"US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connectedWalletId\": \"wallet_abc123\",\n  \"destinationAssetCode\": \"USDC\",\n  \"rail\": \"ach\",\n  \"recipientType\": \"individual\",\n  \"recipientName\": \"Example account\",\n  \"recipientAddress\": {\n    \"street1\": \"example\",\n    \"street2\": \"example\",\n    \"street3\": \"example\",\n    \"city\": \"example\",\n    \"region\": \"example\",\n    \"postalCode\": \"example\",\n    \"country\": \"US\"\n  }\n}"

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

{
  "id": "onramp_acct_123",
  "accountId": "acct_123",
  "status": "provisioning",
  "rail": null,
  "sourceAsset": "USD",
  "destinationAssetCode": "USDC",
  "destinationChainId": 42161,
  "connectedWalletId": "connectedwallet_123",
  "bankName": null,
  "accountNumberLast4": null,
  "createdAt": "2026-08-28T10:00:00.000Z"
}

{
  "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"
  }
}

POST

accounts

{accountId}

onramp-bank-accounts

Issue a persistent on-ramp bank account (US)

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/onramp-bank-accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "connectedWalletId": "wallet_abc123",
  "destinationAssetCode": "USDC",
  "rail": "ach",
  "recipientType": "individual",
  "recipientName": "Example account",
  "recipientAddress": {
    "street1": "example",
    "street2": "example",
    "street3": "example",
    "city": "example",
    "region": "example",
    "postalCode": "example",
    "country": "US"
  }
}
'

import requests

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

payload = {
    "connectedWalletId": "wallet_abc123",
    "destinationAssetCode": "USDC",
    "rail": "ach",
    "recipientType": "individual",
    "recipientName": "Example account",
    "recipientAddress": {
        "street1": "example",
        "street2": "example",
        "street3": "example",
        "city": "example",
        "region": "example",
        "postalCode": "example",
        "country": "US"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    connectedWalletId: 'wallet_abc123',
    destinationAssetCode: 'USDC',
    rail: 'ach',
    recipientType: 'individual',
    recipientName: 'Example account',
    recipientAddress: {
      street1: 'example',
      street2: 'example',
      street3: 'example',
      city: 'example',
      region: 'example',
      postalCode: 'example',
      country: 'US'
    }
  })
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/onramp-bank-accounts', 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}/onramp-bank-accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'connectedWalletId' => 'wallet_abc123',
    'destinationAssetCode' => 'USDC',
    'rail' => 'ach',
    'recipientType' => 'individual',
    'recipientName' => 'Example account',
    'recipientAddress' => [
        'street1' => 'example',
        'street2' => 'example',
        'street3' => 'example',
        'city' => 'example',
        'region' => 'example',
        'postalCode' => 'example',
        'country' => 'US'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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}/onramp-bank-accounts"

	payload := strings.NewReader("{\n  \"connectedWalletId\": \"wallet_abc123\",\n  \"destinationAssetCode\": \"USDC\",\n  \"rail\": \"ach\",\n  \"recipientType\": \"individual\",\n  \"recipientName\": \"Example account\",\n  \"recipientAddress\": {\n    \"street1\": \"example\",\n    \"street2\": \"example\",\n    \"street3\": \"example\",\n    \"city\": \"example\",\n    \"region\": \"example\",\n    \"postalCode\": \"example\",\n    \"country\": \"US\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.post("https://prod-api.stableyard.fi/v2/accounts/{accountId}/onramp-bank-accounts")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connectedWalletId\": \"wallet_abc123\",\n  \"destinationAssetCode\": \"USDC\",\n  \"rail\": \"ach\",\n  \"recipientType\": \"individual\",\n  \"recipientName\": \"Example account\",\n  \"recipientAddress\": {\n    \"street1\": \"example\",\n    \"street2\": \"example\",\n    \"street3\": \"example\",\n    \"city\": \"example\",\n    \"region\": \"example\",\n    \"postalCode\": \"example\",\n    \"country\": \"US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connectedWalletId\": \"wallet_abc123\",\n  \"destinationAssetCode\": \"USDC\",\n  \"rail\": \"ach\",\n  \"recipientType\": \"individual\",\n  \"recipientName\": \"Example account\",\n  \"recipientAddress\": {\n    \"street1\": \"example\",\n    \"street2\": \"example\",\n    \"street3\": \"example\",\n    \"city\": \"example\",\n    \"region\": \"example\",\n    \"postalCode\": \"example\",\n    \"country\": \"US\"\n  }\n}"

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

{
  "id": "onramp_acct_123",
  "accountId": "acct_123",
  "status": "provisioning",
  "rail": null,
  "sourceAsset": "USD",
  "destinationAssetCode": "USDC",
  "destinationChainId": 42161,
  "connectedWalletId": "connectedwallet_123",
  "bankName": null,
  "accountNumberLast4": null,
  "createdAt": "2026-08-28T10:00:00.000Z"
}

{
  "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"
  }
}

Issues a persistent US bank account (ACH, FedWire or FedNow) for the UPA. Incoming USD converts automatically to the chosen destinationAssetCode and is delivered on-chain to the UPA’s connected wallet. There is no separate settlement step, and the account is reusable indefinitely. The UPA needs an active bank_onramp provider relationship (the same regulated-banking relationship used for linked-bank payouts) and an active connected wallet on a verified destination chain and asset pair. Unverified pairs return payment_method_not_supported. Only connectedWalletId and destinationAssetCode are always required in the body. Omit recipientType, recipientName and recipientAddress together to use verified details on file, indicated by recipientOnFile in the requirements response. To override those details, or when none are on file, send all three together. A partial override is rejected. A UPA holds one on-ramp bank account per provider. Repeating the request returns the existing account rather than issuing a second set of banking coordinates. Routing is fixed when the account is issued: a request naming a different connected wallet, chain or destination asset returns 409, and an existing account cannot be re-pointed. Idempotency-Key is required and must contain 8–256 printable characters after trimming surrounding whitespace. Preserve the original body and key through a timeout or provisioning response. Discover eligible rails and wallets through Get on-ramp requirements. The response shows only the bank name and the last four account digits. Call Get deposit instructions for the full details to show the account holder. See On-ramp accounts.

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 funding-account issuance: 8-256 printable characters after trimming surrounding whitespace. Retry the identical request with the same key after a timeout or provisioning response; changed input returns 409 idempotency_conflict.

Required string length: 8 - 256

Pattern: ^[^\u0000-\u001f\u007f]+$

Example:

"bank-funding-account-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

Path Parameters

accountId

string

required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Body

application/json

Omit recipientType, recipientName and recipientAddress to use the name and address already verified for the UPA (see recipientOnFile on the requirements). Send all three together to override them.

connectedWalletId

string

required

Pattern: ^wallet_[A-Za-z0-9_-]{3,59}$

Example:

"wallet_abc123"

destinationAssetCode

enum<string>

required

Only chain/asset pairs Stableyard has verified with the provider are accepted; unverified combinations return payment_method_not_supported.

Available options:

USDC,

USDT

rail

enum<string>

default:ach

Available options:

ach,

fedwire,

fednow

recipientType

enum<string>

Available options:

individual,

business

recipientName

string

Required string length: 1 - 200

recipientAddress

object

Show child attributes

Response

On-ramp bank account

string

required

Example:

"onramp_acct_123"

accountId

string

required

status

enum<string>

required

Available options:

provisioning,

active,

requires_intervention,

disabled,

retired

rail

enum<string> | null

required

Available options:

ach,

fedwire,

fednow,

null

sourceAsset

string

required

Example:

"USD"

destinationAssetCode

string

required

Example:

"USDC"

destinationChainId

integer

required

Example:

42161

connectedWalletId

string

required

The connected wallet this bank account forwards to. Fixed when the bank account is issued: the provider cannot re-point an existing account, so a different wallet, chain or asset requires a different bank account entirely.

bankName

string | null

required

accountNumberLast4

string | null

required

Last 4 digits only. Use the deposit-instructions endpoint for the full details.

createdAt

string<date-time>

required

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Issue an on-ramp bank account

Authorizations

Headers

Path Parameters

Body

Response