Address Book | Bitnob API Reference

Overview

The address book stores named, validated blockchain addresses. Addresses are immutable after creation (you cannot change the address string; create a new entry instead). Address book entries are used by whitelist policies to restrict transaction destinations.

List address bookGET/addressbook
Get entryGET/addressbook/:id
Create entryPOST/addressbook
Update entryPUT/addressbook/:id
Delete entryDELETE/addressbook/:id

List Address Book Entries

Use Case

Lists named address book entries in the organization.

List Address Book

Query Parameters

limitinteger

Maximum number of entries to return per page (default 20). Combine with `offset` to paginate large address books.

offsetinteger

Number of entries to skip before returning results (default 0). Use together with `limit` to walk through the full directory.

chainstring

Restrict results to a single blockchain (e.g. `bitcoin`, `ethereum`, `tron`, `solana`). Useful when whitelist policies are scoped per-chain.

searchstring

Free-text search across the entry `name`, `address` string, and `notes` field — handy for finding a counterparty without knowing which chain you saved it under.

statusstring

Filter by lifecycle state: `active` (usable in whitelist policies) or `inactive` (soft-deleted / retired but kept for historical audit reference).

Query

List Address Book Response

successboolean

Indicates whether the API request was successful.

dataAddressBookEntryResponse[]

Array of address book entries matching the query. Each entry is an immutable, named pointer to an on-chain address.

idstring (uuid)

Stable address book entry identifier — referenced by whitelist policies and used by the get/update/delete endpoints.

namestring

Human-readable label for this destination (e.g. `"Binance Hot Wallet"`). Surfaces in approval prompts and transaction history so operators recognise where funds are going.

chainstring

Blockchain this address lives on (`bitcoin`, `ethereum`, `tron`, `solana`, etc.). Address validation at create-time uses this value.

networkstring

Specific network within the chain — typically `mainnet` or a testnet such as `sepolia`, `testnet`, `nile`, `devnet`.

addressstring

The on-chain address itself, validated at creation against `chain`/`network`. Immutable — to change it, deactivate this entry and create a new one.

statusstring

Lifecycle state: `active` entries can be referenced by whitelist policies; `inactive` entries are retired but retained for audit history.

metaobject

Pagination envelope: `total`, `limit`, `offset`, `has_more`.

List Address Book Response

Create Address Book Entry

Use Case

The address is validated against the specified chain before creation. The address string is immutable afterwards.

Create Entry

Request Body

namestringRequired

Human-readable label for the destination (2-100 chars). Shown to operators in approval prompts and transaction history, so use a name they will recognise (e.g. `"Binance Hot Wallet"`, `"Payroll Provider"`).

chainstringRequired

Blockchain the address lives on (`bitcoin`, `ethereum`, `tron`, `solana`, etc.). Used both to validate the address and to scope whitelist policies.

networkstringRequired

Specific network within the chain, typically `mainnet` or a testnet such as `sepolia` / `testnet` / `nile` / `devnet`.

addressstringRequired

The on-chain address (26-128 chars). Validated against `chain` + `network` at creation time and **immutable** afterwards — to change it you must create a new entry.

notesstring

Optional internal note (max 500 chars) — counterparty contact, verification evidence, or any context operators should see when reviewing whitelist policies.

Example Payload

Create Address Book Response

Same shape as List Address Book entries

Returns a single AddressBookEntryResponse — the same per-entry shape documented under List Address Book Response. The newly-created entry starts with status: "active" and includes its created_at timestamp; the address field is immutable from this point forward.

Get / Update / Delete Entry

Use Case

Only name, notes, and status can be updated. The address string is immutable. Delete is a soft-delete.

Get / Update / Delete

Update Request Body

namestring

New display label (2-100 chars). Updating the name changes how the destination appears in approval prompts and audit logs; the underlying address remains unchanged.

notesstring

Replacement internal note (max 500 chars) — typical use is recording new due-diligence outcomes or counterparty changes.

statusstring

`active` to keep the entry usable in whitelist policies, or `inactive` to retire it. Switching to `inactive` is the soft-delete path: existing audit references stay intact but new transactions cannot target this entry.

Example Payload

Get / Update / Delete Entry Response

Same shape as List Address Book entries

Get and update both return a single AddressBookEntryResponse — same field shape as documented under List Address Book Response (with updated_at reflecting the latest change). Delete is a soft-delete: it returns HTTP 204 with no body and flips status to inactive so historical references remain auditable.