Generate addresses

Create addresses from static segments, generate a batch by auto-incrementing the dynamic segment, and group them into a folder.

Once your Vault's schema is ready (Create a Vault), creating an address means choosing values for the static segments; the platform assigns the dynamic segment's index for you. By repeating the request, you get a batch of addresses in the same subtree. For the address model, see Addresses, folders, and access.

Prerequisites

A Vault with a derivation schema. See Create a Vault. The examples use acme-otc.
An access token (see Authentication) and, if address creation is gated, the canCreateAddress permission.
Any HTTP client.

Step 1. Create a single address

Send POST /api/v1/vaults/{code}/addresses with the network code (networkCode) and the static segment values (staticSegments). The dynamic segment's index is assigned automatically.

curl -X POST "[BASE_URL]/api/v1/vaults/acme-otc/addresses" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "networkCode": "tron_network",
    "staticSegments": { "purpose": "invoices", "asset": "usdt" }
  }'

const res = await fetch("[BASE_URL]/api/v1/vaults/acme-otc/addresses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    networkCode: "tron_network",
    staticSegments: { purpose: "invoices", asset: "usdt" },
  }),
});
console.log(await res.json());

res = requests.post(
    "[BASE_URL]/api/v1/vaults/acme-otc/addresses",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={
        "networkCode": "tron_network",
        "staticSegments": {"purpose": "invoices", "asset": "usdt"},
    },
)
print(res.json())

{
  "id": "cmr3f41z20001psp7phmyapw3",
  "address": "TQ5kohbBSdorGoDBmCGUmDL7RUvNr75mBC",
  "network": "tron",
  "derivationPath": "m/44/195/0/0/1"
}

Under the hood, the platform calculates the next free index for this combination of segments, builds the canonical path, and runs the creation through the Policy Engine (action=create_address).

The address is ready to use immediately. No activation or prefunding is needed, since Gas Station covers the fees.

Step 2. Generate a batch

There's no separate batch endpoint; you get a batch through repeated calls. Each call with the same combination of static segments gets the next free index of the dynamic segment, so N requests produce N addresses in the same subtree.

for i in $(seq 1 5); do
  curl -sS -X POST "[BASE_URL]/api/v1/vaults/acme-otc/addresses" \
    -H "Authorization: Bearer $V3_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "networkCode": "tron_network", "staticSegments": { "purpose": "invoices", "asset": "usdt" } }'
done

const body = {
  networkCode: "tron_network",
  staticSegments: { purpose: "invoices", asset: "usdt" },
};

for (let i = 0; i < 5; i++) {
  const res = await fetch("[BASE_URL]/api/v1/vaults/acme-otc/addresses", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.V3_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  console.log((await res.json()).address);
}

body = {
    "networkCode": "tron_network",
    "staticSegments": {"purpose": "invoices", "asset": "usdt"},
}

for _ in range(5):
    res = requests.post(
        "[BASE_URL]/api/v1/vaults/acme-otc/addresses",
        headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
        json=body,
    )
    print(res.json()["address"])

Index calculation is race-safe (SQL MAX with a retry on conflict), so concurrent requests can't claim the same path.

If creation requires approval

If a policy gates address creation, POST /addresses returns 202 with an approval request id instead of an address, so handle both cases. Then:

check the request status: GET /api/v1/vaults/{code}/approval-requests/{id};
the address appears once the request reaches its threshold (APPROVED).

For more on approval requests, see Approvals.

Step 3. Find the created addresses

Check that the addresses have appeared:

curl "[BASE_URL]/api/v1/vaults/acme-otc/addresses?token=usdt" \
  -H "Authorization: Bearer $V3_TOKEN"

GET /api/v1/vaults/{code}/addresses supports the search, token, and access=shared filters.

Step 4. Group addresses into a folder (optional)

If you need to manage and share addresses together, put them in a folder: a single folder grant covers all of its addresses, including ones added later.

# create a folder
curl -X POST "[BASE_URL]/api/v1/vaults/acme-otc/address-folders" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Invoices — USDT" }'

# add an address to it
curl -X POST "[BASE_URL]/api/v1/vaults/acme-otc/address-folders/FOLDER_ID/members" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "addressId": "ADDRESS_ID" }'

// create a folder
const folder = await fetch("[BASE_URL]/api/v1/vaults/acme-otc/address-folders", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.V3_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Invoices — USDT" }),
}).then((r) => r.json());

// add an address
await fetch(`[BASE_URL]/api/v1/vaults/acme-otc/address-folders/${folder.id}/members`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.V3_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ addressId: "ADDRESS_ID" }),
});

# create a folder
folder = requests.post(
    "[BASE_URL]/api/v1/vaults/acme-otc/address-folders",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={"name": "Invoices — USDT"},
).json()

# add an address
requests.post(
    f"[BASE_URL]/api/v1/vaults/acme-otc/address-folders/{folder['id']}/members",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={"addressId": "ADDRESS_ID"},
)

The body field names (name, addressId) are for illustration only. Check the exact schemas for folders and their members in the API Reference.

Common mistakes

Symptom	Cause
`networkCode` not recognized	the network isn't connected to the Vault, or the code is wrong
segment value rejected	the static option doesn't exist in the schema or is `disabled`
`403` on creation	missing `canCreateAddress` permission, or forbidden by a policy
got `202` instead of an address	creation is gated and awaiting approval (see above)

You're done when

the new addresses are visible in GET /api/v1/vaults/{code}/addresses;
the derivationPath matches your schema (m/44/{coinType}/...);
(optional) the addresses are grouped into a folder.

Next steps

Send a transfer

Next step: send funds from these addresses.

Share and revoke access

Share access to addresses and folders.

Addresses, folders, and access

How access, folders, and visibility isolation work.

API Reference

Exact schemas for creating addresses and folders.

Was this page helpful?