程序化开户与 API key 创建

面向 AI Agent、脚本与 CI 自动化流程，通过以太坊钱包签名（EIP-191）无需浏览器自主完成开户与 API key 创建。

面向在无浏览器环境中运行的自主 AI Agent、CI 自动化流水线与脚本，BlockVectra 提供基于以太坊钱包签名（EIP-4361 / EIP-191）的程序化登录与自动开户流程。

密钥安全

私钥、会话令牌和 API key 不要贴进与 AI 的对话、不要作为 MCP 工具参数。

流程概览

程序化开户与创建 API key 包含四个步骤：

获取 challenge：向 POST /auth/siwe/challenge 发送请求，获取服务端生成的签名消息。
对消息签名：使用以太坊 EOA 钱包，通过 EIP-191（personal_sign）对消息原文进行签名。
登录 / 自动开户：将消息原文与签名提交至 POST /auth/siwe/login。钱包首次登录会自动开户（account_created: true）。新账户注册即得 3,000 万 CU，无需信用卡。
创建 API key：携带返回的会话令牌调用 POST /keys，创建 API key。

Base 地址与程序化模式

所有控制面认证与 key 管理接口均使用正式 Base 地址：

https://console-api.blockvectra.com/v1

不带 Origin 请求头

程序化请求工作在程序化模式：

challenge（POST /auth/siwe/challenge）和 login（POST /auth/siwe/login）两个请求都不带 Origin 请求头（curl 与常用 HTTP 客户端默认不附带该头；请勿手动添加）。
在程序化模式下，服务端签发的消息中 domain 固定为 console-api.blockvectra.com，URI 固定为 https://console-api.blockvectra.com。
若请求中带有 Origin 请求头，但取值不是配置的网页控制台域名（包括空值或 null），challenge 请求直接返回 HTTP 400 invalid_request。
若登录时提交的模式与 challenge 时的模式不一致（例如以程序化模式获取 challenge 后，提交 login 时附带了 Origin 请求头，反之亦然），login 请求返回 HTTP 400 siwe_invalid，原因码为 domain_mismatch。

消息原文与钱包要求

原样签名、原样提交：客户端必须对 challenge 返回的 message 原文进行签名并原样提交，严禁修改任何空格、换行、域名或链 ID。服务端在验签前会将提交的消息与服务端存储的消息逐字节比对；篡改任何内容均会返回 HTTP 400 siwe_invalid，原因码为 signature。
支持的钱包：以太坊主网（Chain ID 1）的 EOA（Externally Owned Account）钱包。签名必须为 65 字节 ECDSA 签名（personal_sign）。不支持合约钱包（EIP-1271）与智能账户（smart accounts）。
challenge 有效期：每个 challenge 的 nonce 仅限使用一次，5 分钟内有效。

会话令牌与 API key

会话令牌生命周期

格式：rgs_ + 64 位小写十六进制字符串。
有效期：绝对有效 7 天；连续空闲 24 小时后失效。
无 refresh token：会话失效后重新执行 challenge 与 login 流程获取新令牌。
传递方式：在请求头中传入 Authorization: Bearer rgs_...。

创建 API key

携带会话令牌调用 POST /keys，创建 API key（rgw_ + 64 位十六进制字符串）。
响应中的 api_key 只出现这一次，请立即妥善保存至密钥管理系统或环境变量中。
一个 API key 可用于所有支持链的 JSON-RPC 与 Data API。

开户限流（`signup_rate_limited`）

为保障服务稳定性，新开户操作受开户限额约束：

超出限额时，POST /auth/siwe/login 返回 HTTP 429 signup_rate_limited，并带有 Retry-After 响应头（秒数）。
错误体中的 reason 字段区分限额维度：
- per_ip：同一 IP 前缀的开户预算已耗尽。
- global：全平台开户上限已耗尽。
开户限流仅在新建账户时生效，已有账户登录不受开户限流影响。

完整 Bash 示例

以下脚本从环境变量 $ADDR 读取钱包地址，从密钥管理读取钱包私钥 $PK，完成 challenge、签名、登录、建 key 全流程，将生成的 key 写入环境变量 BLOCKVECTRA_API_KEY，并通过请求头调用一次 eth_blockNumber：

BASE=https://console-api.blockvectra.com/v1
# $ADDR: 以太坊钱包地址 (0x...)
# $PK: 钱包私钥，从密钥管理系统读入（严禁写进脚本或命令历史）

# 1. 获取服务端签发的 SIWE 消息（不带 Origin 请求头）
curl -s "$BASE/auth/siwe/challenge" -H 'Content-Type: application/json' \
  -d "{\"address\":\"$ADDR\",\"purpose\":\"login\"}" > challenge.json
jq -r .message challenge.json > msg.txt

# 2. 用钱包对消息原文做 EIP-191 personal_sign 签名
SIG=$(cast wallet sign --private-key "$PK" "$(cat msg.txt)")

# 3. 原样提交消息原文与签名（同样不带 Origin 请求头）完成登录
jq -n --rawfile m msg.txt --arg s "$SIG" '{message: ($m | rtrimstr("\n")), signature: $s}' |
  curl -s "$BASE/auth/siwe/login" -H 'Content-Type: application/json' -d @- > session.json
TOKEN=$(jq -r .session.token session.json)

# 4. 创建 API key（secret 仅返回一次）
KEY_RESP=$(curl -s "$BASE/keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"agent-key"}')
export BLOCKVECTRA_API_KEY=$(echo "$KEY_RESP" | jq -r .api_key)

# 5. 用请求头携带 key 发送 JSON-RPC 请求
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

下一步

浏览数据集目录，查看 BlockVectra 索引的全部数据集。
查看免费额度与定价，确认账户可用的方案。
登录控制台创建 API key。

程序化开户与建 Key：面向 Agent 与 CI 的钱包签名指南