Create an account Vault

Create account vault

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/vault \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "ownershipMode": "external",
  "owner": {
    "type": "external_owner",
    "addressType": "evm",
    "address": "0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
  },
  "managedContact": {
    "email": "[email protected]"
  },
  "initialPolicy": {
    "spendLimit": {
      "amountAtomic": "500000000"
    },
    "allowedTokens": [
      "USDC"
    ],
    "yield": {
      "provider": "none"
    }
  }
}
'

import requests

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

payload = {
    "ownershipMode": "external",
    "owner": {
        "type": "external_owner",
        "addressType": "evm",
        "address": "0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
    },
    "managedContact": { "email": "[email protected]" },
    "initialPolicy": {
        "spendLimit": { "amountAtomic": "500000000" },
        "allowedTokens": ["USDC"],
        "yield": { "provider": "none" }
    }
}
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({
    ownershipMode: 'external',
    owner: {
      type: 'external_owner',
      addressType: 'evm',
      address: '0xdFD4ab80E163D6864E26F37540563cBf2E52A582'
    },
    managedContact: {email: '[email protected]'},
    initialPolicy: {
      spendLimit: {amountAtomic: '500000000'},
      allowedTokens: ['USDC'],
      yield: {provider: 'none'}
    }
  })
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/vault', 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}/vault",
  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([
    'ownershipMode' => 'external',
    'owner' => [
        'type' => 'external_owner',
        'addressType' => 'evm',
        'address' => '0xdFD4ab80E163D6864E26F37540563cBf2E52A582'
    ],
    'managedContact' => [
        'email' => '[email protected]'
    ],
    'initialPolicy' => [
        'spendLimit' => [
                'amountAtomic' => '500000000'
        ],
        'allowedTokens' => [
                'USDC'
        ],
        'yield' => [
                'provider' => 'none'
        ]
    ]
  ]),
  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}/vault"

	payload := strings.NewReader("{\n  \"ownershipMode\": \"external\",\n  \"owner\": {\n    \"type\": \"external_owner\",\n    \"addressType\": \"evm\",\n    \"address\": \"0xdFD4ab80E163D6864E26F37540563cBf2E52A582\"\n  },\n  \"managedContact\": {\n    \"email\": \"[email protected]\"\n  },\n  \"initialPolicy\": {\n    \"spendLimit\": {\n      \"amountAtomic\": \"500000000\"\n    },\n    \"allowedTokens\": [\n      \"USDC\"\n    ],\n    \"yield\": {\n      \"provider\": \"none\"\n    }\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}/vault")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ownershipMode\": \"external\",\n  \"owner\": {\n    \"type\": \"external_owner\",\n    \"addressType\": \"evm\",\n    \"address\": \"0xdFD4ab80E163D6864E26F37540563cBf2E52A582\"\n  },\n  \"managedContact\": {\n    \"email\": \"[email protected]\"\n  },\n  \"initialPolicy\": {\n    \"spendLimit\": {\n      \"amountAtomic\": \"500000000\"\n    },\n    \"allowedTokens\": [\n      \"USDC\"\n    ],\n    \"yield\": {\n      \"provider\": \"none\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"ownershipMode\": \"external\",\n  \"owner\": {\n    \"type\": \"external_owner\",\n    \"addressType\": \"evm\",\n    \"address\": \"0xdFD4ab80E163D6864E26F37540563cBf2E52A582\"\n  },\n  \"managedContact\": {\n    \"email\": \"[email protected]\"\n  },\n  \"initialPolicy\": {\n    \"spendLimit\": {\n      \"amountAtomic\": \"500000000\"\n    },\n    \"allowedTokens\": [\n      \"USDC\"\n    ],\n    \"yield\": {\n      \"provider\": \"none\"\n    }\n  }\n}"

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

{
  "id": "vault_123",
  "accountId": "acct_123",
  "chainId": 42161,
  "ownershipMode": "external",
  "status": "pending_authorization",
  "predictedSafeAddress": null,
  "monitoring": {
    "provider": "alchemy",
    "status": "registered",
    "registeredAt": null
  },
  "earning": {
    "enabled": true,
    "provider": "none",
    "currentApyBps": null,
    "earnedAmountRaw": null
  },
  "resourceVersion": 1,
  "createdAt": "2026-08-28T10:00:00.000Z",
  "updatedAt": "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}

vault

Create account vault

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/vault \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "ownershipMode": "external",
  "owner": {
    "type": "external_owner",
    "addressType": "evm",
    "address": "0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
  },
  "managedContact": {
    "email": "[email protected]"
  },
  "initialPolicy": {
    "spendLimit": {
      "amountAtomic": "500000000"
    },
    "allowedTokens": [
      "USDC"
    ],
    "yield": {
      "provider": "none"
    }
  }
}
'

import requests

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

payload = {
    "ownershipMode": "external",
    "owner": {
        "type": "external_owner",
        "addressType": "evm",
        "address": "0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
    },
    "managedContact": { "email": "[email protected]" },
    "initialPolicy": {
        "spendLimit": { "amountAtomic": "500000000" },
        "allowedTokens": ["USDC"],
        "yield": { "provider": "none" }
    }
}
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({
    ownershipMode: 'external',
    owner: {
      type: 'external_owner',
      addressType: 'evm',
      address: '0xdFD4ab80E163D6864E26F37540563cBf2E52A582'
    },
    managedContact: {email: '[email protected]'},
    initialPolicy: {
      spendLimit: {amountAtomic: '500000000'},
      allowedTokens: ['USDC'],
      yield: {provider: 'none'}
    }
  })
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/vault', 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}/vault",
  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([
    'ownershipMode' => 'external',
    'owner' => [
        'type' => 'external_owner',
        'addressType' => 'evm',
        'address' => '0xdFD4ab80E163D6864E26F37540563cBf2E52A582'
    ],
    'managedContact' => [
        'email' => '[email protected]'
    ],
    'initialPolicy' => [
        'spendLimit' => [
                'amountAtomic' => '500000000'
        ],
        'allowedTokens' => [
                'USDC'
        ],
        'yield' => [
                'provider' => 'none'
        ]
    ]
  ]),
  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}/vault"

	payload := strings.NewReader("{\n  \"ownershipMode\": \"external\",\n  \"owner\": {\n    \"type\": \"external_owner\",\n    \"addressType\": \"evm\",\n    \"address\": \"0xdFD4ab80E163D6864E26F37540563cBf2E52A582\"\n  },\n  \"managedContact\": {\n    \"email\": \"[email protected]\"\n  },\n  \"initialPolicy\": {\n    \"spendLimit\": {\n      \"amountAtomic\": \"500000000\"\n    },\n    \"allowedTokens\": [\n      \"USDC\"\n    ],\n    \"yield\": {\n      \"provider\": \"none\"\n    }\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}/vault")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ownershipMode\": \"external\",\n  \"owner\": {\n    \"type\": \"external_owner\",\n    \"addressType\": \"evm\",\n    \"address\": \"0xdFD4ab80E163D6864E26F37540563cBf2E52A582\"\n  },\n  \"managedContact\": {\n    \"email\": \"[email protected]\"\n  },\n  \"initialPolicy\": {\n    \"spendLimit\": {\n      \"amountAtomic\": \"500000000\"\n    },\n    \"allowedTokens\": [\n      \"USDC\"\n    ],\n    \"yield\": {\n      \"provider\": \"none\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"ownershipMode\": \"external\",\n  \"owner\": {\n    \"type\": \"external_owner\",\n    \"addressType\": \"evm\",\n    \"address\": \"0xdFD4ab80E163D6864E26F37540563cBf2E52A582\"\n  },\n  \"managedContact\": {\n    \"email\": \"[email protected]\"\n  },\n  \"initialPolicy\": {\n    \"spendLimit\": {\n      \"amountAtomic\": \"500000000\"\n    },\n    \"allowedTokens\": [\n      \"USDC\"\n    ],\n    \"yield\": {\n      \"provider\": \"none\"\n    }\n  }\n}"

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

{
  "id": "vault_123",
  "accountId": "acct_123",
  "chainId": 42161,
  "ownershipMode": "external",
  "status": "pending_authorization",
  "predictedSafeAddress": null,
  "monitoring": {
    "provider": "alchemy",
    "status": "registered",
    "registeredAt": null
  },
  "earning": {
    "enabled": true,
    "provider": "none",
    "currentApyBps": null,
    "earnedAmountRaw": null
  },
  "resourceVersion": 1,
  "createdAt": "2026-08-28T10:00:00.000Z",
  "updatedAt": "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"
  }
}

Each account has one Vault, on a chain Stableyard configures; you cannot select it. Choose an ownershipMode:

stableyard returns a persisted predictedSafeAddress with status provisioning while deployment and policy installation continue in the background. That confirms the address is allocated, not deployed: wait for status active or the vault.policy_active webhook before funding or using the Vault. An already verified account email authorizes the initial managed policy automatically; otherwise complete the returned contact-verification action. managedContact must match the UPA’s verified email if it has one. The configured platform multisig is the final owner.
external is for account owners who sign policy changes themselves.

Idempotency-Key is required; reuse it only with the identical request. See Treasury settlement.

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. Reuse only with the identical vault request.

Example:

"payment-request-001"

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

ownershipMode

enum<string>

required

Available options:

external,

stableyard

owner

object

Show child attributes

managedContact

object

Canonical UPA email used for managed policy authorization. The initial policy OTP also verifies this email for KYC and fiat services. If the UPA already has a verified email, this value must match it.

Show child attributes

initialPolicy

object

Show child attributes

Response

Vault

string

required

Example:

"vault_123"

accountId

string

required

Example:

"acct_123"

chainId

integer

required

Example:

42161

ownershipMode

enum<string>

required

Available options:

external,

stableyard

status

enum<string>

required

Available options:

pending_authorization,

provisioning,

awaiting_policy,

active,

suspended,

failed,

requires_intervention

monitoring

object

required

Show child attributes

earning

object

required

Show child attributes

resourceVersion

integer

required

Required range: x >= 1

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

safeAddress

string | null

predictedSafeAddress

string | null

Allocated Safe address, persisted before managed creation returns. The address is not evidence of deployment or readiness to receive funds. Wait for status active before funding or using the Vault.

rolesModuleAddress

string | null

activePolicyId

string | null

activePolicy

Active Vault policy · object | null

Show child attributes

latestPolicy

Latest Vault policy · object | null

Show child attributes

nextAction

Vault action required · object | null

Show child attributes

pendingActions

object[]

Show child attributes

spendUsage

object

Show child attributes

mandates

object[]

failureCode

string | null

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Create an account Vault

Authorizations

Headers

Path Parameters

Body

Response