Put Crypto Destination Addresses

Updates a specified crypto destination address. If the address does not exist, it will be created

PUT /transfer/crypto-destination-address

Put Crypto Destination Addresses

cURL

curl --request PUT \
  --url https://api.paxos.com/v2/transfer/crypto-destination-address \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "identity_id": "<string>",
  "address": "<string>",
  "nickname": "<string>",
  "bookmarked_status": true,
  "travelrule_metadata": {
    "beneficiary": {
      "self": true
    },
    "vasp": {
      "id": "<string>",
      "custom_vasp_name": "<string>",
      "custom_vasp_website": "<string>"
    },
    "transfer_purpose": "<string>"
  },
  "memo": "<string>"
}
'

200

{
  "address": {
    "id": "31f20a34-c1eb-4c86-adad-1e46bc271e1a",
    "crypto_network": "ETHEREUM",
    "address": "0xe4B0aCA9FB669817775274775b20e52118595515",
    "nickname": "my_new_address",
    "status": "APPROVED",
    "created_at": "2024-01-01T00:00:00Z",
    "bookmarked": true
  }
}

OAuth Scope

transfer:write_crypto_destination_address

Bookmarked addresses and status

A bookmarked address is saved to your address book. The Addresses page in the Paxos Dashboard shows exactly your bookmarked addresses. Adding an address in the Dashboard bookmarks it. To bookmark an address through the API, set "bookmarked_status": true on Put Crypto Destination Address.

status only applies to bookmarked addresses. It is the approval state of the saved address:

Status	Meaning
PENDING	The bookmarked address is waiting for a second team member to approve it under your Dashboard Approvals policy.
APPROVED	The bookmarked address is approved. Addresses bookmarked through the API are approved immediately.
REJECTED	A team member rejected the bookmarked address under your Dashboard Approvals policy.

status reflects your organization’s own approval settings. It is not a Paxos compliance review. APPROVED means the address passed your approval process, not that Paxos cleared it.

Empty fields are omitted

The API omits empty fields from the JSON response. When an address is not bookmarked, the response omits both status and bookmarked (because bookmarked is false). This is expected behavior. Calling List Crypto Destination Addresses returns the same result, so polling does not produce a status for an address that isn’t bookmarked.

To get a status back, bookmark the address by including "bookmarked_status": true in your PUT request. For API requests, the response includes "bookmarked": true and "status": "APPROVED".

Withdrawals and Travel Rule data

• You can create crypto withdrawals through the API to addresses that are not bookmarked.
• Bookmarking is required for withdrawals created in the Paxos Dashboard, or when Paxos has configured your account to require it for API withdrawals.
• Paxos stores and checks the address’s travelrule_metadata whether or not the address is bookmarked. See the Travel Rule guide.

Each (crypto_network, address, identity_id) combination is a separate record. If you have one record for an address linked to an Identity and another with no identity_id, bookmark the record your withdrawals use.

Memo and destination tags

Some networks route transfers sent to a shared address by a secondary value, called a memo on Stellar and Cosmos and a destination tag on the XRP Ledger. To save a destination that requires one, include memo in the request. The saved address in the response includes memo, and so does each item returned by List Crypto Destination Addresses. Like other empty fields, memo is omitted when the address has none.

memo is accepted only for the following networks, and the Dashboard shows the field for the same networks:

crypto_network	Value of memo	Accepted format
STELLAR	Memo text	UTF-8 text of up to 28 bytes. Leading and trailing whitespace is removed, and the memo cannot contain only whitespace.
RIPPLE	XRP destination tag	A whole number from 0 to 4294967295 with no leading zeros, sent as a string such as "123456".
COSMOS	Memo text	UTF-8 text of up to 256 bytes. Leading and trailing whitespace is removed, and the memo cannot contain only whitespace.

Any other crypto_network rejects a request that includes memo. For the Dashboard equivalent, see Memos and destination tags.

curl -X PUT https://api.sandbox.paxos.com/v2/transfer/crypto-destination-address \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "crypto_network": "RIPPLE",
    "address": "{xrp_address}",
    "nickname": "exchange-xrp",
"memo": "123456",
    "travelrule_metadata": {
      "custodian_type": "VASP",
      "vasp": { "id": "{vasp_id}" },
      "beneficiary": {
        "person_details": {
          "first_name": "{first_name}",
          "last_name": "{last_name}",
          "physical_address": { "country": "USA" }
        }
      }
    }
  }'

Keep the following in mind:

• The combination of crypto_network, address, and memo identifies a saved destination. The same address with a different memo is a separate saved destination, so a request with a new memo creates a new destination instead of updating the existing one.
• To update an existing destination by id, leave memo out of the request. Sending memo together with id returns an error.
• A saved memo cannot be changed. To use a different memo, save the address again with the new value.

Authorizations

Authorization · string · header · required

Paxos APIs use OAuth 2 with the client credentials grant flow.

Token URLs:

• Production: https://oauth.paxos.com/oauth2/token
• Sandbox: https://oauth.sandbox.paxos.com/oauth2/token

Learn more in the API credentials guide →

Body

application/json

id · string

Optional field to specify the crypto destination address to update by its unique id. Specify either id or the (crypto_network, address, identity_id) tuple, not both.

identity_id · string

The Identity that owns this destination address. Required for 3P integrations. When looking up an existing address to update, (crypto_network, address, identity_id) uniquely identifies it; omit for first-party addresses with no identity scope.

crypto_network · enum<string>

A CryptoNetwork is a blockchain transmitting cryptocurrencies.

Available options: BITCOIN, ETHEREUM, BITCOIN_CASH, LITECOIN, SOLANA, POLYGON_POS, BASE, ARBITRUM_ONE, STELLAR, INK, XLAYER, AVALANCHE, DOGECOIN, SUI, ROBINHOOD, BNB, OP, COSMOS, TRON, APTOS, HYPEREVM, MANTLE, RIPPLE, STABLE

address · string

Specify the address of the crypto destination address to create/update. Specify either id or the (crypto_network, address, identity_id) tuple, not both.

nickname · string

Optional field to update the nickname of the crypto destination address. Defaults to an auto-generated nickname if not specified on creation.

bookmarked_status · boolean

Optional field to update the bookmarked status of the crypto destination address. Defaults to false if not specified on creation.

travelrule_metadata · object

Travel Rule metadata for the destination address. See the Travel Rule guide.

Show child attributes

memo · string

Optional memo to save with the destination. Supported only for the following networks:

• STELLAR: UTF-8 text of up to 28 bytes. Leading and trailing whitespace is removed, and the memo cannot be only whitespace.
• RIPPLE: the XRP destination tag, an integer from 0 to 4294967295 written without leading zeros, for example 123456.
• COSMOS: UTF-8 text of up to 256 bytes. Leading and trailing whitespace is removed, and the memo cannot be only whitespace.

Any other network returns an error. When creating a destination, (crypto_network, address, memo) identifies it, so the same address with a different memo is saved as a separate destination. A memo cannot be changed after creation, and it cannot be combined with id.

Response

200 - application/json

A successful response.

address · object

Show child attributes

Example:

{
  "id": "31f20a34-c1eb-4c86-adad-1e46bc271e1a",
  "crypto_network": "ETHEREUM",
  "address": "0xe4B0aCA9FB669817775274775b20e52118595515",
  "nickname": "my_new_address",
  "status": "APPROVED",
  "created_at": "2024-01-01T00:00:00Z",
  "bookmarked": true
}