> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 面向 Agent 的 Crypto RPC

> 将 Venice 同时用作自主 AI agent 的模型提供方和区块链 RPC 层 —— 一份凭证、230+ 模型、11 条链，无需 MetaMask。

Venice 通过单个凭证同时为您的 agent 提供推理能力（230+ 模型）和区块链访问能力（10 条 EVM 链加 Starknet）。您的 agent 可以思考、签名并发送交易，而无需在推理和 RPC 提供商之间周旋多个账户。

<CardGroup cols={2}>
  <Card title="一个凭证，两大超能力" icon="key">
    使用单个 API 密钥（或钱包）同时进行 LLM 推理和 JSON-RPC 调用。
  </Card>

  <Card title="支持 11 条链" icon="link">
    Ethereum、Base、Arbitrum、Optimism、Polygon、Linea、Avalanche、BSC、Blast、zkSync Era 和 Starknet（主网加测试网）。
  </Card>

  <Card title="质押 VVV 实现无人值守资金注入" icon="coins">
    在 Base 上质押 VVV 以每日赚取 DIEM，这是为已铸造 API 密钥提供资金的唯一完全无人值守路径。也可以通过仪表板进行 USD 和加密货币充值。
  </Card>

  <Card title="通过 x402 实现无密钥认证" icon="wallet">
    Agent 可以使用钱包签名进行身份验证，并以 USDC 在 Base 或 Solana 上支付。
  </Card>
</CardGroup>

## 为什么选择 Venice 作为链上 agent 的方案？

| 能力             | 您的 agent 可获得什么                                  |
| -------------- | ----------------------------------------------- |
| **推理**         | 通过一个 OpenAI 兼容端点访问 230+ 文本、图像、视频、音频和嵌入模型        |
| **Crypto RPC** | 到 10 条 EVM 链加 Starknet（主网和测试网）的 JSON-RPC 2.0 代理 |
| **身份验证**       | 标准 API 密钥或 x402 钱包认证（不需要 Venice 账户）             |
| **资金**         | 自主：通过 VVV 质押获取每日 DIEM。浏览器：通过仪表板 USD 或加密货币充值     |
| **批处理**        | 单次请求最多 100 个 JSON-RPC 调用，可跨链并行                  |
| **幂等性**        | 使用 `Idempotency-Key` 头实现安全重试                    |

## 身份验证

选择与您的 agent 运行方式匹配的认证方法。

| 方法          | 最适合              | 工作原理                                                                                                                    |
| ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **API 密钥**  | 服务端 agent、固定部署   | `Authorization: Bearer <key>` 头。在 [venice.ai/settings/api](https://venice.ai/settings/api) 获取密钥。                        |
| **x402 钱包** | 自主、原生加密或短期 agent | 钱包签署 Sign-In-With-X 消息，使用 Base 或 Solana 上的 USDC 按请求付费。无需 Venice 账户。请参阅 [x402 指南](/guides/integrations/x402-venice-api)。 |

两种方法在 Venice credit 中共享相同的速率限制和计费。

<Tip>
  真正自主的 agent 可以通过在 Base 上质押 VVV 来铸造自己的 API 密钥。请参阅 [Autonomous Agent API Key Creation](/guides/getting-started/generating-api-key-agent)。
</Tip>

## Crypto RPC 快速上手

将任何 JSON-RPC 2.0 方法发送到 `POST /crypto/rpc/{network}`。

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'
```

响应：

```json theme={"system"}
{ "jsonrpc": "2.0", "id": 1, "result": "0x1" }
```

响应头包括 `X-Venice-RPC-Credits`（收取的 credit）、`X-Venice-RPC-Cost-USD`（美元成本）和 `X-Request-ID`（关联 ID）。

### 支持的网络

| 系列                | 主网                  | 测试网                                   |
| ----------------- | ------------------- | ------------------------------------- |
| Ethereum          | `ethereum-mainnet`  | `ethereum-sepolia`、`ethereum-holesky` |
| Base              | `base-mainnet`      | `base-sepolia`                        |
| Arbitrum          | `arbitrum-mainnet`  | `arbitrum-sepolia`                    |
| Optimism          | `optimism-mainnet`  | `optimism-sepolia`                    |
| Polygon           | `polygon-mainnet`   | `polygon-amoy`                        |
| Linea             | `linea-mainnet`     | `linea-sepolia`                       |
| Avalanche C-Chain | `avalanche-mainnet` | `avalanche-fuji`                      |
| BNB Smart Chain   | `bsc-mainnet`       | `bsc-testnet`                         |
| Blast             | `blast-mainnet`     | `blast-sepolia`                       |
| zkSync Era        | `zksync-mainnet`    | `zksync-sepolia`                      |
| Starknet          | `starknet-mainnet`  | `starknet-sepolia`                    |

使用 [`GET /crypto/rpc/networks`](/api-reference/endpoint/crypto/networks) 获取实时的权威列表。

### 方法层级

方法分为三个 credit 层级。总成本 = `baseCredits[chain] × methodTier`。

| 层级           | 倍数 | 示例                                                                                                                                 |
| ------------ | -- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Standard** | 1x | `eth_call`、`eth_getBalance`、`eth_blockNumber`、`eth_sendRawTransaction`、`eth_getLogs`、`eth_getTransactionReceipt`、`eth_estimateGas` |
| **Advanced** | 2x | `trace_block`、`trace_call`、`trace_transaction`、`debug_traceCall`、`debug_traceTransaction`                                          |
| **Large**    | 4x | `trace_replayBlockTransactions`、`trace_replayTransaction`、`txpool_content`                                                         |

完整列表和定价详情见 [Crypto RPC API 参考](/api-reference/endpoint/crypto/rpc)。

## Agent 配方

需要进行链上读写的 AI agent 的常见模式。

### 读取钱包的原生代币余额

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xYourWalletAddress", "latest"],
    "id": 1
  }'
```

### 读取 ERC-20 代币余额

使用 `eth_call` 调用 `balanceOf(address)` 选择器。`data` 字段是 4 字节选择器（`0x70a08231`），后跟左填充到 32 字节的钱包地址。最简单的方法是让库进行编码：

```typescript theme={"system"}
import { encodeFunctionData, parseAbi } from 'viem'

const data = encodeFunctionData({
  abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
  args: ['0xWalletAddress'],
})

const response = await fetch('https://api.venice.ai/api/v1/crypto/rpc/base-mainnet', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_call',
    params: [{ to: '0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf', data }, 'latest'],
    id: 1,
  }),
})
```

上面的合约地址是 Base 上的 VVV。可将其换成任何 ERC-20 合约。

### 发送已签名的交易（完整生命周期）

Venice 永不持有您的私钥。agent 通过 RPC 读取收集 tx 参数，使用 [viem](https://viem.sh) 或 [ethers](https://docs.ethers.org) 等库在本地签名，然后通过 Venice 中继原始十六进制。

<Steps>
  <Step title="获取下一个 nonce">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xAgentWallet","pending"],"id":1}'
    ```

    使用 `"pending"`，这样背靠背的发送不会冲突。
  </Step>

  <Step title="获取 gas price">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'
    ```

    对于 EIP-1559 链，倾向于使用 `eth_feeHistory` 计算 `maxFeePerGas` 和 `maxPriorityFeePerGas`。
  </Step>

  <Step title="估算 gas">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xAgentWallet","to":"0xRecipient","value":"0x0","data":"0x..."}],"id":1}'
    ```
  </Step>

  <Step title="本地签名">
    ```typescript theme={"system"}
    import { privateKeyToAccount } from 'viem/accounts'
    import { base } from 'viem/chains'

    const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY)

    const signed = await account.signTransaction({
      chainId: base.id,
      nonce,                  // from step 1
      gas,                    // from step 3
      maxFeePerGas,           // from step 2 (fee history)
      maxPriorityFeePerGas,   // from step 2 (fee history)
      to: '0xRecipient',
      value: 0n,
      data: '0x...',
    })
    ```
  </Step>

  <Step title="通过 Venice 提交">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Idempotency-Key: agent-tx-<id>" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xSignedHex"],"id":1}'
    ```

    在中继时始终设置 `Idempotency-Key`，这样网络抖动也不会重复广播。
  </Step>

  <Step title="轮询接收凭证">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xTxHash"],"id":1}'
    ```

    每隔几秒轮询一次，直到 `result` 非空。检查 `result.status`（`"0x1"` = 成功）。
  </Step>
</Steps>

<Note>
  每次 `eth_sendRawTransaction` 调用都会在服务端记录 tx 哈希、网络、请求 ID 和调用用户 ID。签名负载本身不会保留。此审计追踪的存在是为了使被泄露密钥用于非法中继的情况可以追溯到负责账户。
</Note>

### 批量多个调用（多链组合检查）

在一个请求中发送最多 100 个 JSON-RPC 对象。每个都独立验证和计费。

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 },
    { "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0xWallet", "latest"], "id": 2 },
    { "jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 3 }
  ]'
```

对于多链读取（每条链一次调用），向不同的 `{network}` 端点发起并行请求。

### 使用幂等性实现安全重试

将 `Idempotency-Key` 头设置为匹配 `[A-Za-z0-9_-]{1,255}` 的任意字符串。Venice 以 `(user, key)` 为键将响应缓存 24 小时。重放返回缓存结果，带有 `Idempotent-Replayed: true` 且不收取费用。

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Idempotency-Key: agent-tx-2026-04-21-001" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0xSignedRawTxHex"],
    "id": 1
  }'
```

这对于交易中继至关重要，否则网络抖动可能导致您的 agent 重复广播同一笔 tx。

## 为 agent 的 API 密钥注入资金

agent 拥有 Venice API 密钥后，底层账户需要有可用余额，付费端点才会接受该密钥。有两种方式注入余额：

| 路径                      | 是否自主？  | 工作原理                                                                                                                                                                                                      |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **通过 VVV 质押获取 DIEM**    | 是      | 在 Base 上的 [Venice 质押智能合约](https://basescan.org/address/0x321b7ff75154472B18EDb199033fF4D116F340Ff#code) 中质押 VVV。钱包的每日 DIEM 分配额与其在质押池中的份额成比例。账户需要累计至少 0.1 DIEM 才能消费。DIEM 在 UTC 00:00 刷新。要增加每日消费，可质押更多 VVV。 |
| **通过仪表板进行 USD 或加密货币充值** | 否（浏览器） | 使用相同的钱包登录 [venice.ai](https://venice.ai)（Sign-In-With-Ethereum），然后在 Settings、API 中添加 credit。Stripe（信用卡）和 Coinbase（加密货币）都在该页面之后，并且需要浏览器。Credit 永不过期。                                                       |

对于无人值守运行的 agent，**通过 VVV 质押获取 DIEM 是目前为已铸造 API 密钥提供资金的唯一完全无人值守路径**。如果 agent 的每日消费超过其 DIEM 分配，现实选项是：质押更多 VVV，或让操作员登录并使用 USD 或加密货币充值。

### 自主 VVV 质押和密钥生成

真正自主的 agent 可以在 Base 上管理自己的 VVV 钱包、质押它，并铸造自己的 Venice API 密钥，无需任何人为介入。完整流程：

<Steps>
  <Step title="获取 VVV 和用于 gas 的 ETH">
    向 agent 的钱包发送 VVV（或让 agent 在 [Aerodrome](https://aerodrome.finance) 或 [Uniswap](https://app.uniswap.org) 上交换），外加少量 Base 上的 ETH 用于两次质押交易。
  </Step>

  <Step title="质押 VVV">
    在 VVV 代币上 `approve` 质押合约，然后在 `0x321b7ff75154472B18EDb199033fF4D116F340Ff` 上调用 `stake(amount)`。钱包的 sVVV 余额随质押原子性更新。
  </Step>

  <Step title="铸造 API 密钥">
    `GET /api/v1/api_keys/generate_web3_key` 返回一个在发行 15 分钟后过期的 JWT。使用质押钱包对原始 token 进行签名，然后将地址、签名和 token `POST` 回去。Venice 返回一个绑定到由该钱包派生的用户账户的 API 密钥。
  </Step>
</Steps>

铸造只需要非零的 sVVV 余额，因此质押 1 个 VVV 就足以获得密钥。**使用**密钥进行消费是另一回事，由上面的资金表管理。

请参阅 [Autonomous Agent API Key Creation](/guides/getting-started/generating-api-key-agent) 获取带代码和完整错误参考的完整演练。

## 30 秒内了解 x402 钱包认证

如果您的 agent 已经有 Base 或 Solana 钱包，可以完全跳过 API 密钥。[`venice-x402-client`](https://github.com/veniceai/x402-client) SDK 处理 Sign-In-With-X 签名、充值和余额跟踪。

```bash theme={"system"}
npm install venice-x402-client
```

```typescript theme={"system"}
import { VeniceClient } from 'venice-x402-client'

const venice = new VeniceClient(process.env.WALLET_KEY)

await venice.topUp(10) // skip if the wallet already has balance

const response = await venice.chat({
  model: 'kimi-k2-6',
  messages: [{ role: 'user', content: 'What is the latest block on Base?' }]
})
```

相同的钱包认证适用于 `/crypto/rpc/{network}` 进行区块链读写。完整的协议详情见 [x402 指南](/guides/integrations/x402-venice-api)。

## 定价

Crypto RPC 以 Venice credit 计费。每个响应都包含 `X-Venice-RPC-Credits`（收取的 credit）和 `X-Venice-RPC-Cost-USD`（美元成本），以便您的 agent 跟踪每个请求的消费。

### 各链基础 credit

| 基础 credit | 链                                                                          |
| --------- | -------------------------------------------------------------------------- |
| **20**    | Ethereum、Base、Optimism、Arbitrum、Polygon、Linea、Avalanche、BSC、Blast、Starknet |
| **30**    | zkSync Era                                                                 |

### 成本示例

观察到的 standard、advanced 和 large 方法层级的定价：

| 调用                                             | Credits | 美元成本          |
| ---------------------------------------------- | ------- | ------------- |
| Ethereum 上的 `eth_call`（20 × 1x）                | 20      | \~\$0.0000140 |
| Ethereum 上的 `trace_transaction`（20 × 2x）       | 40      | \~\$0.0000280 |
| Ethereum 上的 `trace_replayTransaction`（20 × 4x） | 80      | \~\$0.0000560 |
| zkSync 上的 `eth_call`（30 × 1x）                  | 30      | \~\$0.0000210 |

始终以 `X-Venice-RPC-Cost-USD` 响应头作为权威成本。批量请求中出错的项目按每项 5 credit 固定计费。

### 速率限制

| 层级       | 每分钟请求数 |
| -------- | ------ |
| Standard | 100    |
| Staff    | 1,000  |

超出时，端点返回 `429` 和标准的 `X-RateLimit-*` 响应头。

## 错误处理

您的 agent 应处理的常见 HTTP 响应：

| 状态    | 含义                                                                        | 应对方式                                                                                                                                                                    |
| ----- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | 不支持或未映射的 JSON-RPC 方法，或批量格式错误                                              | 根据[白名单](/api-reference/endpoint/crypto/rpc)验证方法。错误正文会指明违规方法。                                                                                                            |
| `400` | 使用不同正文重放 `Idempotency-Key`                                                | 对不同请求使用新的密钥。                                                                                                                                                            |
| `402` | 完全没有 auth 头（响应正文包含 `authOptions` 列出两种支持的 auth 路径），或带有有效 auth 头但 credit 不足 | 如果无 auth：附加 `Authorization: Bearer ...` 或 x402 `X-Sign-In-With-X` 头。如果 credit 不足：使用 Bearer 密钥时，为账户注入资金（DIEM、USD 或仪表板充值）；使用 x402 auth 时，直接调用 `POST /api/v1/x402/top-up`。 |
| `429` | 达到速率限制（standard 100 req/min，staff 1,000 req/min）                          | 尊重 `X-RateLimit-Reset` 并退避。每个请求最多批量 100 个调用以分摊限制。                                                                                                                       |
| `5xx` | 上游 RPC 节点故障                                                               | 使用相同的 `Idempotency-Key` 重试以避免重复扣费。                                                                                                                                      |

每项批量错误（例如 N 个调用中的某一个参数无效）会在 `200 OK` 响应内返回，违规项带有 JSON-RPC `error` 字段。这些项按每项 5 credit 固定计费。

## 不支持

这些类别的方法被有意拒绝：

* **仅 WebSocket**（`eth_subscribe`、`eth_unsubscribe`）：代理仅支持 HTTP。请改为轮询。
* **有状态过滤器**（`eth_newFilter`、`eth_getFilterChanges` 等）：过滤器状态绑定到单个后端，在负载均衡代理上会失效。请改用 `eth_getLogs`。
* **持有密钥的方法**（`eth_sign`、`eth_accounts`、`eth_mining`）：托管提供商不持有用户密钥。在客户端签名并通过 `eth_sendRawTransaction` 提交。
* **未映射的方法**：任何未列入白名单的方法都返回 `400`。如需添加，请联系支持。

## 资源

<CardGroup cols={2}>
  <Card title="Crypto RPC API 参考" icon="code" href="/api-reference/endpoint/crypto/rpc">
    完整方法列表、定价和响应头
  </Card>

  <Card title="支持的网络" icon="link" href="/api-reference/endpoint/crypto/networks">
    支持网络 slug 的实时列表
  </Card>

  <Card title="x402 钱包认证" icon="wallet" href="/guides/integrations/x402-venice-api">
    使用 Base 或 Solana 钱包进行认证和支付
  </Card>

  <Card title="自主 Agent API 密钥" icon="robot" href="/guides/getting-started/generating-api-key-agent">
    通过质押 VVV 铸造您自己的密钥
  </Card>

  <Card title="Postman Collection" icon="play" href="https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-2cf5a817-41cd-438b-ad37-5d07c3f13005?action=share&creator=48156591&active-environment=38652128-ef110f4e-d3e1-43b5-8029-4d6877e62041">
    27 个可立即运行的 Crypto RPC 示例
  </Card>

  <Card title="定价" icon="coins" href="/overview/pricing">
    DIEM、credit 定价和支付选项
  </Card>
</CardGroup>