Endpoint

Propose a saved address

POST/v1/saved_addresses

Proposes an address that money can later be sent to. Nothing can be sent to it yet: an Owner or Finance member approves it in the dashboard with a passkey, every Owner is emailed, and it becomes active 24 hours after approval (awaiting_approval, then waiting, then active). See money out.

Scope a restricted key needs: payouts:write
Publishable key: Not allowed: secret or restricted key only
Idempotency-Key: Required. A request without it is refused.

Parameters

Parameters of Propose a saved address
Parameter	Type and place	Meaning
`Orrerie-Version`	stringheader	API version date. Default: the version the key was created with. Example `2026-10-11`.
`Idempotency-Key`required	stringheader	Required here: a person at your business approves what this request asks for (money out, or a new saved address), and a retry with the same key never asks for it twice. 1 to 255 characters.

Request body

A JSON object. The body is required. A field the call does not list is refused with parameter_unknown.

Request body of Propose a saved address
Field	Type	Meaning
`label`required	string	Up to 100 characters.
`address`required	string	Checked for the network's format and checksum; exact case is kept on non-EVM networks.
`network`required	string	One of the eleven network ids.
`asset`	string	Restrict the address to one asset. Default: any asset on the network.
`kind`	string	Default `third_party`. `own` marks an address of the merchant's own (payouts to it are withdrawals). One of `own`, `third_party`.
`metadata`	object	Your own key-value data (rules in Metadata).

Example request

curl

curl https://api.orrerie.com/v1/saved_addresses \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Green bean supplier",
  "address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
  "network": "base",
  "asset": "base:usdc"
}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/saved_addresses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
    "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "label": "Green bean supplier",
    "address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
    "network": "base",
    "asset": "base:usdc"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

Python

import os
import requests

response = requests.post(
    "https://api.orrerie.com/v1/saved_addresses",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}", "Idempotency-Key": "8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a"},
    json={
        "label": "Green bean supplier",
        "address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
        "network": "base",
        "asset": "base:usdc",
    },
    timeout=30,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

PHP

<?php
$request = curl_init('https://api.orrerie.com/v1/saved_addresses');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORRERIE_SECRET_KEY'),
        'Idempotency-Key: 8f14e45f-ceea-467f-a9d2-6f1c2b3d4e5a',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'label' => 'Green bean supplier',
        'address' => '0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb',
        'network' => 'base',
        'asset' => 'base:usdc',
    ]),
]);
$body = curl_exec($request);
if ($body === false) {
    throw new RuntimeException(curl_error($request));
}
$result = json_decode($body, true);
if (curl_getinfo($request, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
print_r($result);

Responses

`202` Accepted

The request was accepted and is waiting: for a person to approve it in the dashboard, or to be built in the background. Nothing has been signed or sent. The answer is the saved_address object. Headers: Orrerie-Request-Id.

Example response, 202

{
  "id": "dst_92jw0br3z1bzkk45ddjqcm6q",
  "object": "saved_address",
  "livemode": true,
  "created": "2026-10-05T11:20:00.000Z",
  "label": "Green bean supplier",
  "kind": "third_party",
  "address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
  "network": "base",
  "asset": "base:usdc",
  "status": "awaiting_approval",
  "approved_by": null,
  "approved_at": null,
  "usable_at": null,
  "screening": {
    "id": "scr_6ncr4e0p7wqndfvny2d5vw5s",
    "status": "clear",
    "checked_at": "2026-10-05T11:20:01.000Z"
  },
  "approval_url": "https://merchant.orrerie.com/approve/dst_92jw0br3z1bzkk45ddjqcm6q",
  "metadata": {}
}

Any other status: an error

A status of 400 or above answers with the error object. Branch on its code, never on its message.

Errors

Beside the errors every call can answer with (a bad key, a missing scope, the rate limit), this call answers with:

Errors of Propose a saved address
Code	HTTP	Meaning
`idempotency_key_required`	400	The endpoint moves money on approval (refunds, payouts, batches, conversions, saved addresses) and needs an `Idempotency-Key`.
`destination_invalid`	400	The address fails the network's format or checksum, or does not match the asset's network.
`destination_blocked`	403	The destination address is on a sanctions list. The request is refused and recorded.
`screening_unavailable`	503	The sanctions check could not be made. A failed check is never treated as clean; retry later.