---
title: "Create Address Book"
method: POST
path: "/v1/ramp/wallet_address"
tags: ["Address Book"]
---

# Create Address Book

`POST /v1/ramp/wallet_address`

Create wallet address book entry, supporting Exchange addresses and Personal Wallet addresses. Automatic address risk assessment and validation is performed.
[  *Stablecoin Account API Publisher Disclaimer*](/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer)

## Headers

- `x-on-behalf-of` string
- `x-idempotency-key` string, uuid

## Request body

- AddressBookCreateRequest
  - `address_label` string, required — Address label/name
  - `network` string, required — Network code
  - `currency` string, required — Currency code
  - `address_type` integer, required — Address type (1000: Exchange, 2000: Personal Wallet)
  - `wallet_address` string, required — Wallet address
  - `address_source` string — Address source (required if address_type=1000)
  - `legal_declaration` 'I_CERTIFY_BENEFICIAL_OWNERSHIP_OF_EXCHANGE_ACCOUNT' | 'I_CERTIFY_THIS_ADDRESS_IS_MINE', required — address_type=1000: I_CERTIFY_BENEFICIAL_OWNERSHIP_OF_EXCHANGE_ACCOUNT; address_type=2000: I_CERTIFY_THIS_ADDRESS_IS_MINE
  - `is_whitelist` integer — Whether to add this address to the whitelist (0: No, 1: Yes)
  - `meta_data` TravelRuleMetaData — Travel Rule data for a counterparty — either a withdrawal destination (address book entry) or a deposit originator (via Submit Deposit Sender Travel Rule). It is required for third-party counterparties (`address_party=third_party`) and hosted wallets (`wallet_type=hosted`).
    - `wallet_type` 'hosted' | 'unhosted', required — Custody type of the destination wallet — `hosted` for a custodial/exchange wallet (requires VASP details), `unhosted` for a self-custody/private wallet.
    - `address_party` 'first_party' | 'third_party', required — Ownership of the address — `first_party` when it belongs to the account holder, `third_party` when it belongs to another beneficiary.
    - `beneficiary_information` BeneficiaryInformation — Beneficiary information for the destination address. Individual beneficiaries provide name fields; corporate beneficiaries provide the company name. Hosted wallets additionally require VASP details.
      - `entity_type` 'individual' | 'corporation' — Beneficiary entity type. Required when `address_party=third_party`.
      - `first_name` string — Beneficiary given name. Required for an individual third-party beneficiary.
      - `last_name` string — Beneficiary family name. Required for an individual third-party beneficiary.
      - `company_name` string — Beneficiary company name. Required for a corporate third-party beneficiary.
      - `country` string — Beneficiary country code (ISO 3166-1 alpha-2, lowercase). Required for a third party. Use a `countryCode` returned by the Country List endpoint.
      - `city` string — Beneficiary city/region. Required for a third party. Use a `regionName` returned by the Region List endpoint.
      - `vasp_id` string — Beneficiary VASP identifier. Required for a hosted wallet (provide at least one of `vasp_id` / `vasp_name`). Use an `identifier` returned by the VASP List endpoint.
      - `vasp_name` string — VASP name. For a hosted wallet, supply the exchange name here when the VASP is not found in the VASP List (in which case `vasp_id` may be omitted).
      - `id_type` string — Beneficiary identity document type. Optional.
      - `id_primary` string — Beneficiary identity document number. Optional.

## Response `200`

Address book entry created successfully

- AddressBookCreateResponse
  - `code` integer, required
  - `message` string, required
  - `data` AddressBookEntry, required
    - `account_id` string, required — Account ID
    - `address_id` string, uuid, required — Address entry ID
    - `address_type` integer, required — Address type (1000: Exchange, 2000: Personal Wallet)
    - `address_label` string, required — Address label/name
    - `network` string, required — Network code
    - `currency` string, required — Currency code
    - `wallet_address` string, required — Wallet address
    - `create_time` string, required — Creation time
    - `address_status` integer, required — Address status
    - `is_owner` integer, required — Whether user owns this address (0: No, 1: Yes)
    - `receiver_name` string, required — Receiver name
    - `verification_status` integer, required — Verification status (1: Verified, 2: Failed)
    - `need_travel_rule` boolean — Whether this address still needs Travel Rule data. `true` when `meta_data` is empty; use it to prompt the user to complete the information before withdrawing.
    - `meta_data` TravelRuleMetaData — Travel Rule data for a counterparty — either a withdrawal destination (address book entry) or a deposit originator (via Submit Deposit Sender Travel Rule). It is required for third-party counterparties (`address_party=third_party`) and hosted wallets (`wallet_type=hosted`).
      - `wallet_type` 'hosted' | 'unhosted', required — Custody type of the destination wallet — `hosted` for a custodial/exchange wallet (requires VASP details), `unhosted` for a self-custody/private wallet.
      - `address_party` 'first_party' | 'third_party', required — Ownership of the address — `first_party` when it belongs to the account holder, `third_party` when it belongs to another beneficiary.
      - `beneficiary_information` BeneficiaryInformation — Beneficiary information for the destination address. Individual beneficiaries provide name fields; corporate beneficiaries provide the company name. Hosted wallets additionally require VASP details.
        - `entity_type` 'individual' | 'corporation' — Beneficiary entity type. Required when `address_party=third_party`.
        - `first_name` string — Beneficiary given name. Required for an individual third-party beneficiary.
        - `last_name` string — Beneficiary family name. Required for an individual third-party beneficiary.
        - `company_name` string — Beneficiary company name. Required for a corporate third-party beneficiary.
        - `country` string — Beneficiary country code (ISO 3166-1 alpha-2, lowercase). Required for a third party. Use a `countryCode` returned by the Country List endpoint.
        - `city` string — Beneficiary city/region. Required for a third party. Use a `regionName` returned by the Region List endpoint.
        - `vasp_id` string — Beneficiary VASP identifier. Required for a hosted wallet (provide at least one of `vasp_id` / `vasp_name`). Use an `identifier` returned by the VASP List endpoint.
        - `vasp_name` string — VASP name. For a hosted wallet, supply the exchange name here when the VASP is not found in the VASP List (in which case `vasp_id` may be omitted).
        - `id_type` string — Beneficiary identity document type. Optional.
        - `id_primary` string — Beneficiary identity document number. Optional.
    - `message` string — Error message (returned on failure)

---

[API](https://skmtc.dev/uqpay/apis/authentication-api.md) · [All operations](https://skmtc.dev/uqpay/apis/authentication-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uqpay/authentication-api/revisions/cef532a10777/schema)