Register a hosted wallet address

Register a wallet that is custodied by another VASP (e.g. Coinbase, Kraken) on behalf of the customer. This is required by the Travel Rule before the wallet can be used in any flow — onramp, offramp, or swap.

Provide the VASP’s DID (Decentralized Identifier) so Iron can exchange travel-rule data with the custodian. Use the Search VASPs endpoint to look up the correct DID.

POST /addresses/crypto/hosted

Register a hosted wallet address

cURL

curl --request POST \
  --url https://api.sandbox.iron.xyz/api/addresses/crypto/hosted \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'IDEMPOTENCY-KEY: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vasp_did": "<string>",
  "wallet_address": "<string>",
  "name": "<string>"
}
'

import requests

url = "https://api.sandbox.iron.xyz/api/addresses/crypto/hosted"

payload = {
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "vasp_did": "<string>",
    "wallet_address": "<string>",
    "name": "<string>"
}
headers = {
    "IDEMPOTENCY-KEY": "<idempotency-key>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json; charset=utf-8"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'IDEMPOTENCY-KEY': '<idempotency-key>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json; charset=utf-8'
  },
  body: JSON.stringify({
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    vasp_did: '<string>',
    wallet_address: '<string>',
    name: '<string>'
  })
};

fetch('https://api.sandbox.iron.xyz/api/addresses/crypto/hosted', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.iron.xyz/api/addresses/crypto/hosted",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'vasp_did' => '<string>',
    'wallet_address' => '<string>',
    'name' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json; charset=utf-8",
    "IDEMPOTENCY-KEY: <idempotency-key>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.iron.xyz/api/addresses/crypto/hosted"

	payload := strings.NewReader("{\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"vasp_did\": \"<string>\",\n  \"wallet_address\": \"<string>\",\n  \"name\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("IDEMPOTENCY-KEY", "<idempotency-key>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json; charset=utf-8")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.iron.xyz/api/addresses/crypto/hosted")
  .header("IDEMPOTENCY-KEY", "<idempotency-key>")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json; charset=utf-8")
  .body("{\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"vasp_did\": \"<string>\",\n  \"wallet_address\": \"<string>\",\n  \"name\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.iron.xyz/api/addresses/crypto/hosted")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["IDEMPOTENCY-KEY"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json; charset=utf-8'
request.body = "{\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"vasp_did\": \"<string>\",\n  \"wallet_address\": \"<string>\",\n  \"name\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "address_type": "SelfHosted",
  "blockchain": "Solana",
  "created_at": "2024-01-15T10:30:00.000Z",
  "disabled": false,
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "is_self": true,
  "name": "Primary Solana wallet",
  "proof_message": "I hereby verify that I own this wallet address",
  "proof_signature": "5J9qvKhKqYbpjhCkqDnKXSp7QqLDBU5iT4VWshsqRdWKHjKdqZqKqYbpjhCkqDnKXSp...",
  "vasp_did": null,
  "wallet_address": "7QqLDBU5iT4VWshsqRdWKHjKdqZqKqYbpjhCkqDnKXSp"
}

"<string>"

"<string>"

"<string>"

"<string>"

Authorizations

X-API-Key · string · header · required

API Key

Headers

IDEMPOTENCY-KEY · string · required

a UUID ensuring an address is only registered once

X-SUB-PARTNER-ID · string

Optional sub-partner UUID, if provided, the wallet address will be registered for the sub-partner

X-API-Version · string

Selects the API version for this request, as an ISO date (YYYY-MM-DD). Omit to use the default version (2025-03-13). Supported versions: 2025-03-13, 2026-07-01.

Body

application/json; charset=utf-8

The hosted wallet registration request

Hosted wallet registration request

Register a VASP-custodied wallet address for Travel Rule compliance

blockchain · enum<string> · required

Blockchain

A type of blockchain

Available options: Solana, Ethereum, Polygon, Arbitrum, Base, Stellar, Citrea, Plasma, Avalanche, Moca, Tempo, Tron, Bsc

customer_id · string<uuid> · required

The customer ID

vasp_did · string · required

The VASP DID (decentraliced Identifier) that hosts the wallet

wallet_address · string · required

The wallet address at the institution

name · string

Optional display name for this wallet address

Response

200

application/json; charset=utf-8

Registration successful

Verified Address Response

Response containing verified address details

address_type · enum<string> · required

Available options: Hosted, SelfHosted

blockchain · enum<string> · required

Blockchain

A type of blockchain

Available options: Solana, Ethereum, Polygon, Arbitrum, Base, Stellar, Citrea, Plasma, Avalanche, Moca, Tempo, Tron, Bsc

created_at · string<date-time> · required

When the address was verified

disabled · boolean · required

Whether the address is disabled

id · string<uuid> · required

The ID of the verified address

is_self · boolean · required

Whether the wallet belongs to the customer themselves (true) or a third party

wallet_address · string · required

The wallet address

name · string

Optional display name for this wallet address

proof_message · string

The proof message

proof_signature · string

The proof signature

vasp_did · string

The VASP DID (decentralized Identifier) for hosted wallets