跳转到内容

区块链 API 快速入门与 API Key

Chaingateway API 是一套 REST API,通过 HTTPS 和 JSON 为多条区块链创建钱包、发送交易、读取余额并推送 Webhook。调用它需要三样东西:账户、API 令牌和 HTTP 客户端。本指南逐一介绍,并以创建一个 Ethereum 地址的首个请求作结。

请求流程:你的应用通过 HTTPS 发送带 Bearer 令牌和可选 X-Network header 的请求,Chaingateway API 查询区块链并返回 JSON 你的应用 HTTP 客户端:curl、requests、axios、Guzzle 发往 app.chaingateway.io/api/v2/{chain}/... 的 HTTPS 请求 Authorization: Bearer 令牌,可选 X-Network: testnet Chaingateway API 校验令牌和请求体,与区块链通信 JSON 响应 status、ok、message、data
每次调用 API 时都会发生的过程。

先注册账户,再打开 API key 页面并创建令牌。新账户享有 7 天免费试用,开始时无需绑卡。请在 Chaingateway 账户页面创建账户,或者登录,然后打开 API key 页面。

为令牌输入一个名称,然后点击 ”+ Create Token”。新令牌会出现在列表中。请把它保存在安全的地方,不要分享。任何持有该令牌的人都能以你的账户调用 API,所以不要把它放进源代码管理,而应从环境变量或 .env 文件中加载。

任何能发送 HTTPS 请求的客户端都可以。API 参考文档能生成比本页多得多的语言示例。本页的示例使用以下客户端:

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: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,则使用主网络。网络表列出了每个取值对应的网络。

用 POST 请求创建一个 Ethereum 地址。请求体是只有一个字段 password 的 JSON 对象。它保护 Chaingateway 为该地址存储的私钥,之后每次从该地址发送交易时都需要它。如果省略它会怎样,请看钱包管理。

Terminal window
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"
}'

成功的调用返回状态码 201。OpenAPI 文件把地址字段的键拼写为 adderess,所以请按这个名称读取:

{
"status": 201,
"ok": true,
"message": "Address created",
"data": {
"adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8"
}
}

读取数据使用 GET,它没有请求体。下面的调用列出你创建且尚未删除的地址。

Terminal window
curl --request GET \
--url https://app.chaingateway.io/api/v2/ethereum/addresses \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Accept: application/json'

如何在 testnet 上运行同一个调用?

Section titled “如何在 testnet 上运行同一个调用?”

添加 header X-Network: testnet,其余保持不变。地址随后会在 Sepolia 上创建,测试币没有市场价值。请一直使用 testnet,直到你的集成能正确处理成功和错误响应。以后切换到主网时,只需删除该 header 或把它设为 mainnet。

错误使用与成功调用相同的 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,因为它们通常会指出出错的字段或原因。