区块链 API 快速入门与 API Key
Chaingateway API 是一套 REST API,通过 HTTPS 和 JSON 为多条区块链创建钱包、发送交易、读取余额并推送 Webhook。调用它需要三样东西:账户、API 令牌和 HTTP 客户端。本指南逐一介绍,并以创建一个 Ethereum 地址的首个请求作结。
如何创建账户和 API key?
Section titled “如何创建账户和 API key?”先注册账户,再打开 API key 页面并创建令牌。新账户享有 7 天免费试用,开始时无需绑卡。请在 Chaingateway 账户页面创建账户,或者登录,然后打开 API key 页面。
为令牌输入一个名称,然后点击 ”+ Create Token”。新令牌会出现在列表中。请把它保存在安全的地方,不要分享。任何持有该令牌的人都能以你的账户调用 API,所以不要把它放进源代码管理,而应从环境变量或 .env 文件中加载。
应该使用哪种 HTTP 客户端?
Section titled “应该使用哪种 HTTP 客户端?”任何能发送 HTTPS 请求的客户端都可以。API 参考文档能生成比本页多得多的语言示例。本页的示例使用以下客户端:
- 用于 shell 脚本的 curl
- 用于 Python 的 Requests
- 用于 JavaScript 和 Node.js 的 Axios
- 用于 PHP 的 Guzzle,或 Laravel HTTP 客户端
这里的 REST 方法是什么意思?
Section titled “这里的 REST 方法是什么意思?”API 遵循 RFC 9110 中的 HTTP 方法语义。addresses、transactions 和 webhooks 等资源位于 /api/v2/{chain}/ 之下,方法决定对资源执行什么操作。响应为 JSON。
| 方法 | 含义 | 本 API 中的示例 |
|---|---|---|
GET | 读取一个资源或一个列表 | GET /api/v2/ethereum/addresses 列出你的地址 |
POST | 创建资源或触发操作 | POST /api/v2/ethereum/addresses 创建一个地址 |
PUT | 替换现有资源的字段 | PUT /api/v2/ethereum/webhooks/{id} 更新一个 Webhook |
DELETE | 删除资源 | DELETE /api/v2/ethereum/addresses/{address} 删除一个地址 |
地址不能编辑,因为它由密钥决定,所以地址没有 PUT 或 PATCH。已存储密钥的密码是例外,它通过 POST /api/v2/{chain}/addresses/{address} 修改。
每个请求需要哪些 header?
Section titled “每个请求需要哪些 header?”请发送三个 header:Authorization、Accept,以及在请求带有请求体时发送 Content-Type。第四个可选 header 是 X-Network,用于选择测试网络。
Authorization: Bearer YOUR_API_TOKEN按 RFC 6750 的定义,以 Bearer 令牌的形式携带你的令牌。没有有效令牌的请求会收到 HTTP 401,响应体为{"message":"Unauthenticated."}。Accept: application/json要求返回 JSON 响应。Content-Type: application/json告诉服务器请求体是 JSON。API 也接受表单编码的请求体,但示例使用 JSON。X-Network: testnet让请求在测试网络上运行。省略该 header 或发送mainnet,则使用主网络。网络表列出了每个取值对应的网络。
如何发送我的第一个请求?
Section titled “如何发送我的第一个请求?”用 POST 请求创建一个 Ethereum 地址。请求体是只有一个字段 password 的 JSON 对象。它保护 Chaingateway 为该地址存储的私钥,之后每次从该地址发送交易时都需要它。如果省略它会怎样,请看钱包管理。
curl --request POST \ --url https://app.chaingateway.io/api/v2/ethereum/addresses \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "password": "choose-a-strong-password"}'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/addresses"payload = {"password": "choose-a-strong-password"}headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Accept": "application/json", "Content-Type": "application/json",}response = requests.post(url, json=payload, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'POST', url: 'https://app.chaingateway.io/api/v2/ethereum/addresses', headers: { Authorization: 'Bearer YOUR_API_TOKEN', Accept: 'application/json', 'Content-Type': 'application/json', }, data: { password: 'choose-a-strong-password' },};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php$client = new \GuzzleHttp\Client();$response = $client->request('POST', 'https://app.chaingateway.io/api/v2/ethereum/addresses', [ 'json' => ['password' => 'choose-a-strong-password'], 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', 'Accept' => 'application/json', ],]);echo $response->getBody();成功的调用返回状态码 201。OpenAPI 文件把地址字段的键拼写为 adderess,所以请按这个名称读取:
{ "status": 201, "ok": true, "message": "Address created", "data": { "adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8" }}读取数据使用 GET,它没有请求体。下面的调用列出你创建且尚未删除的地址。
curl --request GET \ --url https://app.chaingateway.io/api/v2/ethereum/addresses \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/addresses"headers = {"Authorization": "Bearer YOUR_API_TOKEN", "Accept": "application/json"}response = requests.get(url, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'GET', url: 'https://app.chaingateway.io/api/v2/ethereum/addresses', headers: { Authorization: 'Bearer YOUR_API_TOKEN', Accept: 'application/json' },};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php$client = new \GuzzleHttp\Client();$response = $client->request('GET', 'https://app.chaingateway.io/api/v2/ethereum/addresses', [ 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', 'Accept' => 'application/json', ],]);echo $response->getBody();如何在 testnet 上运行同一个调用?
Section titled “如何在 testnet 上运行同一个调用?”添加 header X-Network: testnet,其余保持不变。地址随后会在 Sepolia 上创建,测试币没有市场价值。请一直使用 testnet,直到你的集成能正确处理成功和错误响应。以后切换到主网时,只需删除该 header 或把它设为 mainnet。
错误响应是什么样的?
Section titled “错误响应是什么样的?”错误使用与成功调用相同的 JSON 外层结构,只是 ok 为 false。OpenAPI 文件记录了状态码 200、201、400、401、404 和 422。校验错误会列出被拒绝的字段:
{ "status": 422, "ok": false, "message": "Data validation failed", "errors": { "password": ["The password field is required."] }}区块链错误也以同样的方式返回。余额不足以支付 gas 的交易会返回 422,并带有节点的消息;钱包密码错误则返回 401 和 Wrong password provided。请在每次失败的调用中记录 message 和 errors,因为它们通常会指出出错的字段或原因。
- RFC 9110, HTTP Semantics 定义了上文使用的方法和状态码。
- RFC 6750, Bearer Token Usage 定义了
Authorization: Bearerheader。 - RFC 8259, JSON 定义了请求体和响应体的格式。
- API 的 OpenAPI 文件列出了每个端点、参数和示例响应。