private/add_to_address_book

Adds a new address to the address book. The address book allows you to store addresses for withdrawals, along with beneficiary information for compliance purposes.

Coinbase wallet type

For Coinbase wallet type accounts the method supports network selection and CTN (Coinbase Travel Network) counterparties, and behaves differently:

• Required parameters are type and label, plus one of:
  • address together with currency and network (optional tag) — an on-chain address on the selected network, or
  • counterparty_id — a CTN counterparty; currency is then omitted and the entry applies to all currencies.
• type accepts only withdrawal and transfer.
• Travel rule data is provided with the fields name, country, address, financial_institution, account, account_location, entity_type (organization or individual), wallet_type (exchange or self_hosted) and is_self instead of the legacy beneficiary_*, agreed and personal fields.
• extra_currencies is not supported.
• The response contains a Coinbase address book entry object, including the entry id which can be used instead of address in the other address book methods.

📖 Related Article: Managing Withdrawals

Scope: wallet:read_write

Try in API console

cURL

cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/private/add_to_address_book \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "private/add_to_address_book",
  "params": {
    "currency": "BTC",
    "type": "withdrawal",
    "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
    "label": "Main address",
    "beneficiary_vasp_name": "Money`s Gone",
    "beneficiary_vasp_did": "did:example:123456789abcdefghi",
    "beneficiary_first_name": "John",
    "beneficiary_last_name": "Doe",
    "beneficiary_address": "NL, Amsterdam, Street, 1",
    "agreed": true,
    "personal": false
  }
}
'

200

response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
    "creation_timestamp": 1536569522277,
    "currency": "BTC",
    "type": "withdrawal",
    "label": "Main address",
    "beneficiary_vasp_name": "Money`s Gone",
    "beneficiary_vasp_did": "did:example:123456789abcdefghi",
    "beneficiary_first_name": "John",
    "beneficiary_last_name": "Doe",
    "beneficiary_address": "NL, Amsterdam, Street, 1",
    "agreed": true,
    "personal": false,
    "info_required": false
  }
}

Query Parameters

currency · enum<string>

The currency symbol. Required for legacy wallet type (wallet currencies only). Coinbase wallet type: required when address is used (any portfolio currency); omitted when adding a CTN counterparty via counterparty_id — such entries apply to all currencies ("all"). Currency, i.e "BTC", "ETH", "USDC"

Available options: BTC, ETH, USDC, USDT, EURR

Example:

"BTC"

type · enum<string> · required

Address book type

Available options: transfer, withdrawal, deposit_source

Example:

"withdrawal"

address · string

Address in currency format. Required for legacy wallet type. Coinbase wallet type: required when counterparty_id is not provided, and must then be used together with currency and network (and tag for networks that require one). For Coinbase wallet type the same value is also stored as the beneficiary address travel rule field. Address in proper format for currency

Example:

"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj"

network · string

Blockchain network for the wallet operation, given as a network resource name (e.g. "networks/ethereum-mainnet"). Coinbase wallet type only. The networks available for each currency are returned by public/get_currencies in the coinbase_networks field. Required for operations that target an on-chain address or a deposit address; also used to disambiguate address book entries when the same address exists on multiple networks.

Example:

"networks/ethereum-mainnet"

tag · string

Destination tag / memo for networks that support one. Coinbase wallet type only. Used together with address and network; also serves to disambiguate address book entries that share the same address.

counterparty_id · string

Identifier of a Coinbase Travel Network (CTN) counterparty. Coinbase wallet type only. Used instead of address and network; entries created with counterparty_id apply to all currencies, so currency is omitted.

Example:

"cp-8f3e2a1b9c4d"

label · string · required

Label of the address book entry

Example:

"Main address"

beneficiary_vasp_name · string

Name of beneficiary VASP

Example:

"Moneys Gone"`

beneficiary_vasp_did · string

DID of beneficiary VASP

Example:

"did:example:123456789abcdefghi"

beneficiary_vasp_website · string

Website of the beneficiary VASP

beneficiary_first_name · string

First name of beneficiary (if beneficiary is a person) First name of the beneficiary (if beneficiary is a person)

Example:

"John"

beneficiary_last_name · string

First name of beneficiary (if beneficiary is a person) Last name of the beneficiary (if beneficiary is a person)

Example:

"Doe"

beneficiary_company_name · string

Beneficiary company name (if beneficiary is a company) Company name of the beneficiary (if beneficiary is a company)

Example:

"Company Name"

beneficiary_address · string

Geographical address of the beneficiary

Example:

"NL, Amsterdam, Street, 1"

agreed · boolean

Indicates that the user agreed to shared provided information with 3rd parties

Example:

true

personal · boolean

The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software

Example:

false

extra_currencies · string[]

The user can pass a list of currencies to add the address for. It is currently available ONLY for ERC20 currencies. Without passing this paramater for an ERC20 currency, the address will be added to ALL of the ERC20 currencies.

Name of the currency

Example:

["USDC"]

name · string

Full name of the beneficiary (person or organization). Coinbase wallet type only — travel rule data.

Example:

"Alice Smith"

country · string

Country code of the beneficiary (ISO 3166-1 alpha-2). Coinbase wallet type only — travel rule data.

Example:

"NL"

financial_institution · string

Name of the financial institution holding the beneficiary account. Coinbase wallet type only — travel rule data.

account · string

Account identifier of the beneficiary at the financial institution. Coinbase wallet type only — travel rule data.

account_location · string

Location of the beneficiary account. Coinbase wallet type only — travel rule data.

entity_type · enum<string>

Type of the beneficiary entity. Coinbase wallet type only — travel rule data.

Available options: organization, individual

wallet_type · enum<string>

Type of the beneficiary wallet. Coinbase wallet type only — travel rule data.

Available options: exchange, self_hosted

is_self · boolean

Indicates that the beneficiary is the account owner. Coinbase wallet type only — travel rule data.

Response

200 - application/json

Success response

jsonrpc · enum<string> · required

The JSON-RPC version (2.0)

Available options: 2.0

result · object · required

Option 1

Option 2

Hide child attributes

result. currency · enum<string> · required

Currency, i.e "BTC", "ETH", "USDC"

Available options: BTC, ETH, STETH, ETHW, USDC, USDT, EURR, SOL, XRP, USYC, PAXG, BNB, USDE

result. address · string · required

Address in proper format for currency

Example:

"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

result. creation_timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result. type · enum<string>

Address book type

Available options: transfer, withdrawal, deposit_source

result. label · string

Label of the address book entry

Example:

"Main address"

result. beneficiary_vasp_name · string

Name of beneficiary VASP

Example:

"Money's Gone"

result. beneficiary_vasp_did · string

DID of beneficiary VASP

Example:

"did:example:123456789abcdefghi"

result. beneficiary_vasp_website · string

Website of the beneficiary VASP

result. beneficiary_first_name · string

First name of the beneficiary (if beneficiary is a person)

Example:

"John"

result. beneficiary_last_name · string

Last name of the beneficiary (if beneficiary is a person)

Example:

"Doe"

result. beneficiary_company_name · string

Company name of the beneficiary (if beneficiary is a company)

Example:

"Company Name"

result. beneficiary_address · string

Geographical address of the beneficiary

Example:

"NL, Amsterdam, Street, 1"

result. agreed · boolean

Indicates that the user agreed to shared provided information with 3rd parties

Example:

true

result. personal · boolean

The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software

Example:

true

result. info_required · boolean

Signalises that addition information regarding the beneficiary of the address is required

Example:

true

result. status · enum<string>

Wallet address status, values: [admin_locked, waiting, confirmed, ready]

Available options: admin_locked, waiting, confirmed, ready

result. waiting_timestamp · boolean

Timestamp when the address will be ready

Example:

true

result. requires_confirmation · boolean

If address requires email confirmation for withdrawals

Example:

true

result. requires_confirmation_change · boolean

If email confirmation change is in progress

Example:

true

result. requires_security_key · boolean

If withdrawals to this address require a security key

Example:

false

id · integer

The id that was sent in the request