Whitelisted Addresses

Whitelisted addresses are external destinations that can be used for transactions. Each address belongs to your client, has an asset type, and moves through a whitelist approval workflow before it can be used.

Create Whitelisted Address

Submits a new external destination for approval. Newly created addresses enter the pending approval workflow before they can be used for transactions.

POST/relay/v1/whitelisted-addresses

Required permission:Initiate external wallet address

Request Body

namerequired

string

Display name for the destination. Maximum 100 characters.

addressrequired

string

External account address. The address must be valid for the requested asset type.

assetTyperequired

string

Asset symbol, such as BTC, ETH, or USDC.

description

string

Optional note for reviewers. Maximum 500 characters.

Example

curl -X POST "https://api.numis-trust.com/relay/v1/whitelisted-addresses" \
  -H "x-api-key: numis_abc123xyz789" \
  -H "x-api-secret: your-api-secret" \
  -H "content-type: application/json" \
  -d '{
    "name": "BTC Treasury Destination",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "assetType": "BTC",
    "description": "Cold storage payout destination"
  }'

const response = await fetch(
  'https://api.numis-trust.com/relay/v1/whitelisted-addresses',
  {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': process.env.NUMIS_API_KEY,
      'x-api-secret': process.env.NUMIS_API_SECRET,
    },
    body: JSON.stringify({
      name: 'BTC Treasury Destination',
      address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
      assetType: 'BTC',
      description: 'Cold storage payout destination',
    }),
  },
);

const address = await response.json();

Response

{
  "id": "6f1e5b20-4a33-45f1-9a2d-7d3a2df5f001",
  "name": "BTC Treasury Destination",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "description": "Cold storage payout destination",
  "status": "PENDING",
  "assetType": "BTC"
}

Response Codes

201Whitelisted address request created successfully.

400Invalid request — malformed body, invalid address for the asset, or unsupported asset type.

401Missing or invalid credentials.

403Credential lacks the Initiate external wallet address permission, or is not client-scoped.

409A matching address already exists for the same client and asset.

429Rate limit exceeded.

List Whitelisted Addresses

Returns a paginated list of whitelisted addresses belonging to your client.

GET/relay/v1/whitelisted-addresses

Required permission:View whitelisted address

Query Parameters

page

integer

Page number. Defaults to 1.

limit

integer

Results per page. Defaults to 20, maximum 100.

assetType

string

Filter by asset symbol, such as BTC, ETH, or USDC. Accepts multiple values.

status

'PENDING' | 'APPROVED' | 'REJECTED' | 'ARCHIVED'

Filter by whitelist status. Accepts multiple values.

Example

curl -X GET "https://api.numis-trust.com/relay/v1/whitelisted-addresses?assetType=BTC&status=APPROVED&page=1&limit=20" \
  -H "x-api-key: numis_abc123xyz789" \
  -H "x-api-secret: your-api-secret"

const params = new URLSearchParams({
  assetType: 'BTC',
  status: 'APPROVED',
  page: '1',
  limit: '20',
});

const response = await fetch(
  `https://api.numis-trust.com/relay/v1/whitelisted-addresses?${params}`,
  {
    headers: {
      'x-api-key': process.env.NUMIS_API_KEY,
      'x-api-secret': process.env.NUMIS_API_SECRET,
    },
  },
);

const { items, total, totalPages } = await response.json();

Response

{
  "items": [
    {
      "id": "6f1e5b20-4a33-45f1-9a2d-7d3a2df5f001",
      "fireblocksId": "8d9f7c4e-18bf-4b8d-9b82-06d1f890ff12",
      "name": "BTC Treasury Destination",
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "status": "APPROVED",
      "assetType": "BTC"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

Response Codes

200Whitelisted addresses retrieved successfully.

400Invalid request — unsupported query parameter, invalid status, or invalid pagination value.

401Missing or invalid credentials.

403Credential lacks the View whitelisted address permission, or is not client-scoped.

429Rate limit exceeded.

Get Whitelisted Address

Returns a single whitelisted address belonging to your client.

GET/relay/v1/whitelisted-addresses/{id}

Required permission:View whitelisted address

Path Parameters

idrequired

uuid

The whitelisted address ID to retrieve.

Example

curl -X GET "https://api.numis-trust.com/relay/v1/whitelisted-addresses/6f1e5b20-4a33-45f1-9a2d-7d3a2df5f001" \
  -H "x-api-key: numis_abc123xyz789" \
  -H "x-api-secret: your-api-secret"

const id = '6f1e5b20-4a33-45f1-9a2d-7d3a2df5f001';
const response = await fetch(
  `https://api.numis-trust.com/relay/v1/whitelisted-addresses/${id}`,
  {
    headers: {
      'x-api-key': process.env.NUMIS_API_KEY,
      'x-api-secret': process.env.NUMIS_API_SECRET,
    },
  },
);

const address = await response.json();

Response

{
  "id": "6f1e5b20-4a33-45f1-9a2d-7d3a2df5f001",
  "fireblocksId": "8d9f7c4e-18bf-4b8d-9b82-06d1f890ff12",
  "name": "BTC Treasury Destination",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "status": "APPROVED",
  "assetType": "BTC"
}

Response Codes

200Whitelisted address retrieved successfully.

400Invalid request — malformed id.

401Missing or invalid credentials.

403Credential lacks the View whitelisted address permission.

404No whitelisted address found for the given id within your client scope.

429Rate limit exceeded.

Status Values

Status	Meaning
`PENDING`	The address has been created and is awaiting approval or activation.
`APPROVED`	The address has completed approval and is available as a transaction destination.
`REJECTED`	The address was rejected during the approval workflow.
`ARCHIVED`	The address has been archived and should not be used for new transactions.

Whitelisted Addresses

Item Fields

On this page