地址 - Blockradar

概述
专属地址使您能够为每个客户创建唯一的区块链地址，用于在多条区块链上无缝接收稳定币充值。

前提条件

在生成专属地址之前，请确保您已完成以下步骤：

API 密钥

从 Blockradar 控制面板获取您的 API 密钥。导航至 Developers 生成密钥。

创建钱包

通过创建钱包 API 或控制面板创建主钱包。地址在主钱包下生成。

为钱包充值

确保您的主钱包有足够的原生代币用于支付 Gas 费用（用于自动归集）。

配置 Webhooks

通过控制面板设置 Webhook 以接收充值通知。详情请参阅 Webhooks。

简介

专属地址是 Blockradar 的核心功能，使您能够为客户创建唯一地址。这些地址允许客户无缝地向您的金融科技应用充值稳定币。当您为客户创建专属地址时，他们可以使用该单一地址在多条 EVM 兼容区块链上充值稳定币。例如，如果您创建了 Ethereum、Binance Smart Chain、Polygon 和 Base 主钱包，则通过这些主钱包中任意一个生成的地址都可用于在任何支持的区块链和资产上接收稳定币。这确保您无需担心客户将稳定币发送到错误的区块链。此外，当稳定币充值到特定地址时，资产会自动转移到该链的主钱包地址。

除了 Tron 和 Solana 外，从一个钱包生成的地址可用于在其他具有区块链参数 isEvmCompatible: true 的区块链上接收稳定币充值。

地址参数说明

创建或更新地址时，您可以使用以下可选参数来自定义其行为：

参数	类型	默认值	描述
`disableAutoSweep`	Boolean（可选）	`false`	如果设置为 `true`，则禁用此地址资金的自动归集。
`enableGaslessWithdraw`	Boolean（可选）	`false`	如果设置为 `true`，允许用户无需直接支付 Gas 费用即可提现。
`metadata`	Object（可选）	`null`	您可以附加到地址的自定义元数据，用于您自己的引用或跟踪目的。
`name`	String（可选）	`null`	地址的可读名称，便于在控制面板或日志中识别。
`showPrivateKey`	Boolean（可选）	`false`	如果设置为 `true`，此地址的私钥将在 API 响应中返回。请谨慎使用。

参数 disableAutoSweep、enableGaslessWithdraw 和 showPrivateKey 将覆盖此特定地址的主钱包配置中的相应设置。无论钱包的默认设置如何，这都允许在地址级别进行精细控制。

注意：

所有这些参数都是可选的；您只需包含与您用例相关的参数。
启用 showPrivateKey 可能会暴露敏感信息。仅在安全、可信的环境中使用。
请谨慎使用 showPrivateKey，暴露私钥可能会危及安全。

创建专属地址

您可以使用 Blockradar 控制面板或 API 为客户生成专属地址，具体取决于您的工作流程和集成需求。

1. 使用控制面板

Blockradar 控制面板提供了简单易用的界面来生成新地址。

此截图演示了通过 Blockradar 控制面板生成新地址的过程。此方法适用于手动创建地址或偏好图形界面的团队。

2. 使用 API

对于程序化或自动化地址生成，您可以使用创建专属地址 API。这对于将地址创建集成到您自己的应用程序或后端系统非常有用。要为客户创建专属地址，请向我们的创建专属地址 API发送 POST 请求。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "disableAutoSweep": "OPTIONAL_BOOLEAN",
  "enableGaslessWithdraw": "OPTIONAL_BOOLEAN",
  "metadata": "OPTIONAL_METADATA",
  "name": "OPTIONAL_ADDRESS_NAME",
  "showPrivateKey": "OPTIONAL_BOOLEAN"
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"metadata":"OPTIONAL_METADATA","name":"OPTIONAL_ADDRESS_NAME"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"metadata\": \"OPTIONAL_METADATA\",\n  \"name\": \"OPTIONAL_ADDRESS_NAME\"\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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;
}

响应

{
  "data": {
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "blockchain": {
      "createdAt": "2024-05-14T11:53:33.095Z",
      "derivationPath": "m/44'/60'/0'/0",
      "id": "85ffc132-3972-4c9e-99a5-5cf0ccb688bf",
      "isActive": true,
      "isEvmCompatible": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800081/crypto-assets/ethereum-eth-logo_idraq2.png",
      "name": "ethereum",
      "slug": "ethereum",
      "symbol": "eth",
      "tokenStandard": "ERC20",
      "updatedAt": "2024-06-14T22:32:11.983Z"
    },
    "configurations": {
      "aml": {
        "message": "Address is not sanctioned",
        "provider": "ofac",
        "status": "success"
      },
      "disableAutoSweep": false,
      "enableGaslessWithdraw": false,
      "showPrivateKey": false
    },
    "createdAt": "2024-10-23T11:13:40.446Z",
    "derivationPath": "m/44'/60'/0'/0/87",
    "id": "0a69c48a-6c6f-422c-bd6a-70de3306a3ac",
    "isActive": true,
    "metadata": {
      "user_id": 1
    },
    "name": "Customer 1",
    "network": "testnet",
    "type": "INTERNAL",
    "updatedAt": "2024-10-23T11:13:40.446Z"
  },
  "message": "Address generated successfully",
  "statusCode": 200
}

地址签发与索引

Blockradar 将以往在创建地址时一起发生的两件事拆分开来：

签发（issue） 地址成本很低。它从您的主钱包派生出一个新地址并存储下来，您可以立即将其交给客户。
索引地址是成本较高的部分。它将地址纳入链上监控，使充值能够被实时检测到，并且索引是计费的依据。

这使您可以提前为每位客户签发一个地址，仅在客户表现出充值意向时才开启索引，因此您只需为真正监控的地址付费。

两个独立的开关

每个地址有两个用于控制其状态的设置：

设置	取值	控制内容
`isActive`	`true` / `false`	主开关。`false` 会完全停用该地址。
`indexingStatus`	`ACTIVE` / `INACTIVE`	监控与计费开关。`INACTIVE` 表示休眠：不被监控，也不被计费。

只有当两者都开启时，地址才会被链上监控并计入计费：isActive: true 且 indexingStatus: ACTIVE。

现有地址不受影响。indexingStatus 默认为 ACTIVE，因此您已创建的每个地址，以及您在不主动选择休眠的情况下创建的每个地址，行为都与以前完全相同。

签发休眠地址

生成地址时，传入 enableIndexing: false 以创建一个不被监控、也不被计费的休眠地址。省略该字段或传入 true 即为默认行为（立即索引）。休眠地址在响应中返回 "indexingStatus": "INACTIVE"。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "name": "Customer 123",
  "metadata": { "customerId": "123" },
  "enableIndexing": false
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"name":"Customer 123","metadata":{"customerId":"123"},"enableIndexing":false}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"name\": \"Customer 123\",\n  \"metadata\": { \"customerId\": \"123\" },\n  \"enableIndexing\": false\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

开启索引

当客户表现出充值意向时开启索引。这会订阅该地址、启动实时监控并将其纳入计费。该调用无需请求体且为幂等操作（若索引已开启则不执行任何操作）。路径参数 addressId 可接受地址 UUID 或链上地址字符串。响应中显示 "indexingStatus": "ACTIVE"。如果地址已被停用（isActive: false），则返回 400。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable \
  --header 'x-api-key: <api-key>'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>'}
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["x-api-key: <api-key>"],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

关闭索引

为已流失或不活跃的客户关闭索引，以停止为您不再监控的地址计费。这会停止监控，并在下一个计费周期将该地址从计费中移除。该调用无需请求体且为幂等操作。已收到的资金在链上仍然安全，您可以稍后重新开启索引，除正常计费外不产生额外费用。响应中显示 "indexingStatus": "INACTIVE"。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable \
  --header 'x-api-key: <api-key>'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>'}
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["x-api-key: <api-key>"],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

计费

地址计费是在每次续订时进行的实时计数，而非按地址收费。每个周期，Blockradar 都会统计在主网上处于活跃且已索引状态的地址，并对超出套餐上限的用量收费。

地址状态	是否计入计费	是否链上监控
休眠（`indexingStatus: INACTIVE`）	否 — 免费	否
已索引（`indexingStatus: ACTIVE`）	是	是
周期中途被关闭	在下次计数中退出	否

生成休眠地址不产生任何费用，关闭索引会在下一个周期释放该名额。

最佳实践

在将地址分配给客户时签发休眠地址。它不产生任何费用。
当客户表现出充值意向时开启索引（KYC 通过、打开结账页、查看充值页面）。
在分享地址用于真实充值之前，务必先开启索引，以便实时检测到充值。
为已流失或不活跃的客户关闭索引，需要时再重新开启。

向休眠地址进行的充值不会被实时检测到。如果客户在索引开启之前向某地址充值，资金在链上是安全的，但不会被自动记录。请开启索引并触发充值查找器以恢复这些充值。为避免此情况，请务必在分享地址前开启索引。

地址白名单

此功能允许您将外部地址加入白名单，以根据钱包的要求进行监控。已经有其他提供商签发的钱包？您仍然可以将它们接入 Blockradar 并监控充值，无需更改您现有的设置。

请求体参数

键	必需	类型	描述
`name`	false	string	地址名称。
`address`	true	string	钱包地址。
`metadata`	false	object	地址的附加元数据。这将成为与此地址相关的任何交易的一部分。
`showPrivateKey`	false	boolean	是否希望地址私钥成为响应的一部分。
`disableAutoSweep`	false	boolean	禁用将发送到该地址的资产自动归集到主钱包。
`enableGaslessWithdraw`	false	boolean	启用此地址的免 Gas 交易。
`privateKey`	false	string	与地址关联的私钥。安全执行操作时需要。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "name": "Whitelisted Address",
  "metadata": {"purpose": "external_monitoring", "source": "manual"},
  "showPrivateKey": false,
  "disableAutoSweep": false,
  "enableGaslessWithdraw": true,
  "privateKey": "0x1234567890abcdef..."
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"address":"ADDRESS_TO_WHITELIST","metadata":"OPTIONAL_METADATA","name":"OPTIONAL_ADDRESS_NAME"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"address\": \"ADDRESS_TO_WHITELIST\",\n  \"metadata\": \"OPTIONAL_METADATA\",\n  \"name\": \"OPTIONAL_ADDRESS_NAME\"\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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;
}

响应

{
  "data": {
    "address": "0x3375154fa32Cb434B044E73a2582C4D2E6518AE4",
    "blockchain": {
      "createdAt": "2024-05-27T08:31:14.966Z",
      "derivationPath": "m/44'/60'/0'/0",
      "id": "74733889-4ecd-403e-9840-94e87c043f24",
      "isActive": true,
      "isEvmCompatible": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800080/crypto-assets/Base_Network_Logo_vqyh7r.png",
      "name": "base",
      "slug": "base",
      "symbol": "eth",
      "tokenStandard": null,
      "updatedAt": "2024-10-27T07:52:16.115Z"
    },
    "configurations": {
      "aml": {
        "message": "Address is not sanctioned",
        "provider": "ofac",
        "status": "success"
      }
    },
    "createdAt": "2024-11-11T16:57:19.160Z",
    "derivationPath": null,
    "id": "b87901a2-45c1-4d2d-8ee7-205ef0c4ddf1",
    "isActive": true,
    "metadata": null,
    "name": "External address",
    "network": "testnet",
    "type": "EXTERNAL",
    "updatedAt": "2024-11-11T16:57:19.160Z"
  },
  "message": "Address whitelisted successfully",
  "statusCode": 200
}

测试

通过测试网主钱包生成的地址只能在测试网上接收资产。

以下是您可以获取测试网资产进行测试的地方列表：

Ethereum - 在此获取测试 USDC：Circle
Binance Smart Chain - 在此获取测试 USDT：Binance
Polygon - 在此获取测试 USDC：Circle
Base - 在此获取测试 USDC：Circle
Tron - 在此获取测试 USDT：Nileex
Solana - 在此获取测试 USDC：Circle
Optimism - 在此获取测试 USDC：Circle
Arbitrum - 在此获取测试 USDC：Circle
Celo - 在此获取测试 USDC：Circle

Happy hacking! 💚

开始使用

钱包

收款

付款

转换与管理

合规与工具

地址

前提条件

简介

地址参数说明

创建专属地址

1. 使用控制面板

2. 使用 API

响应

地址签发与索引

两个独立的开关

签发休眠地址

开启索引

关闭索引

计费

最佳实践

地址白名单

请求体参数

响应

测试

​前提条件

​简介

​地址参数说明

​创建专属地址

​1. 使用控制面板

​2. 使用 API

​响应

​地址签发与索引

​两个独立的开关

​签发休眠地址

​开启索引

​关闭索引

​计费

​最佳实践

​地址白名单

​请求体参数

​响应

​测试

前提条件

简介

地址参数说明

创建专属地址

1. 使用控制面板

2. 使用 API

响应

地址签发与索引

两个独立的开关

签发休眠地址

开启索引

关闭索引

计费

最佳实践

地址白名单

请求体参数

响应

测试