通过 x402 快速开始

x402 协议（也称为 L402）是一种新兴的 API 货币化标准，支持按次付费访问而无需订阅。

Minara x402 端点： https://x402.minara.ai

什么是 x402？

x402 是一种原生的“按用付费”网络系统。你无需预付订阅费，而是使用像 $USDC 这样的稳定币为每次 API 调用直接付费。

主要优势：

• 无需订阅： 仅为你使用的服务付费

• 无需许可的访问： 无需创建账户或审批流程

• 即时激活： 付款后即可立刻开始使用 API

• 加密原生： 在 Base、Solana 或 Polygon 上以 USDC 支付

• 价格透明： 明确知道每次 API 调用的费用

工作原理：

x402 协议遵循支付挑战流程，包含以下关键步骤：

完整流程

1. 初始请求 （客户端 → 服务器）

   • 你向受保护的端点发起 API 请求但未付款

2. 支付挑战 （服务器 → 客户端）

   • 服务器响应 402 Payment Required 状态

   • 返回支付说明（金额、货币、接收地址、链）

3. 支付选择 （客户端）

   • 你选择支付方式并创建支付负载

   • 准备在指定链上使用 USDC 支付

4. 已认证请求 （客户端 → 服务器）

   • 在以下位置包含支付证明 x-payment-response 头部

   • 重试原始请求

5. 验证 （服务器 → 协调方）

   • 服务器将支付证明发送给协调方进行验证

   • 确认支付有效性

6. 支付处理 （协调方 → 区块链）

   • 协调方向区块链提交交易

   • 交易在链上确认

7. 结算 （协调方 → 服务器）

   • 协调方向服务器确认结算

   • 支付完成

8. 访问授予 （服务器 → 客户端）

   • 你收到 API 响应

   • 支付收据包含在 X-PAYMENT-RESPONSE 头部

关键组件

• 客户端： 发起 API 请求的你的应用

• 服务器： Minara API 端点（https://x402.minara.ai)

• 协调方： 支付验证与结算服务

• 区块链： 链上支付结算（Base、Solana 或 Polygon）

---

如何在 Minara 上使用 x402

1. 使用 x402 SDK（推荐）

大多数开发者使用官方 x402 SDK， 自动处理所有支付流程.

你只需发起请求：SDK 会为你处理支付挑战、验证和结算。

先决条件

在开始之前，请确保你已具备：

• 一个持有 USDC 的加密钱包（任何兼容 EVM 的钱包）

• Node.js 和 npm、Go，或 Python 与 pip

• 你的钱包私钥（用于对支付进行签名）

步骤 1：安装依赖

Node.js / TypeScript

# 适用于基于 fetch 的客户端（推荐）
npm install @x402/fetch @x402/evm

# 适用于基于 axios 的客户端
npm install @x402/axios @x402/evm

# 如需 Solana 支持，还需添加：
npm install @x402/svm

Python

# 适用于 httpx（异步）- 推荐
pip install "x402[httpx]"

# 适用于 requests（同步）
pip install "x402[requests]"

# 如需 Solana 支持，还需添加：
pip install "x402[svm]"

Go

go get github.com/coinbase/x402/go

步骤 2：设置你的钱包签名器

Node.js（使用 viem）

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// 从私钥创建签名器（使用环境变量）
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

对于 Solana：

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

Python（使用 eth-account）

pip install eth_account

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

Go

import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

步骤 3：发起请求：支付自动处理！

SDK 会自动为你处理支付挑战。只需像平常一样发起请求！

Node.js（使用 fetch）

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// 创建签名器
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// 创建 x402 客户端并注册 EVM 方案
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// 将 fetch 包装以支持支付处理
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// 发起请求 - 支付将自动处理！🎉
const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userQuery: "当前 BTC 的价格是多少？"
  })
});

const data = await response.json();
console.log("Response:", data.content);

// 获取支付收据（可选）
if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}

📖 GitHub 上的完整示例

Node.js（使用 axios）

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// 创建签名器
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// 创建 x402 客户端并注册 EVM 方案
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// 创建带有支付处理的 Axios 实例
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: "https://x402.minara.ai" }),
  client
);

// 发起请求 - 支付将自动处理！🎉
const response = await api.post("/x402/chat", {
  userQuery: "分析 ETH 的价格走势"
});

console.log("Response:", response.data.content);

📖 GitHub 上的完整示例

Python（使用 httpx 异步）

import asyncio
import os
from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def call_minara():
    # 创建客户端并注册 EVM 方案
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # 发起请求 - 支付将自动处理！🎉
    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "BTC 的价格是多少？"}
        )
        await response.aread()
        
        data = response.json()
        print(f"Response: {data['content']}")


asyncio.run(call_minara())

📖 GitHub 上的完整示例

Python（使用 requests 同步）

import os
from eth_account import Account

from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


def call_minara():
    # 创建客户端并注册 EVM 方案
    client = x402ClientSync()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # 发起请求 - 支付将自动处理！🎉
    with x402_requests(client) as session:
        response = session.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "BTC 的价格是多少？"}
        )
        
        data = response.json()
        print(f"Response: {data['content']}")


call_minara()

📖 GitHub 上的完整示例

Go

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/client"
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

func main() {
    // 创建 EVM 签名器
    evmSigner, _ := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))

    // 创建 x402 客户端并注册 EVM 方案
    x402Client := x402.Newx402Client().
        Register("eip155:*", evm.NewExactEvmScheme(evmSigner))

    // 用支付处理包装 HTTP 客户端
    httpClient := x402http.WrapHTTPClientWithPayment(
        http.DefaultClient,
        x402http.Newx402HTTPClient(x402Client),
    )

    // 准备请求体
    reqBody := map[string]string{"userQuery": "BTC 的价格是多少？"}
    jsonData, _ := json.Marshal(reqBody)

    // 发起请求 - 支付将自动处理！🎉
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    req, _ := http.NewRequestWithContext(ctx, "POST", "https://x402.minara.ai/x402/chat", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("请求失败: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Response: %v\n", data["content"])
}

📖 GitHub 上的完整示例

多链支持（Base + Solana + Polygon）

你可以注册多个支付方案以支持所有 Minara 链：

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// 为不同链创建签名器
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

// 创建包含多种方案的客户端
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });  // Base + Polygon
registerExactSvmScheme(client, { signer: svmSigner });  // Solana

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// 现在你可以调用任何 Minara 端点！🚀
// Base 端点
await fetchWithPayment("https://x402.minara.ai/x402/chat", {...});

// Solana 端点  
await fetchWithPayment("https://x402.minara.ai/x402/solana/chat", {...});

// Polygon 端点
await fetchWithPayment("https://x402.minara.ai/x402/polygon/chat", {...});

完整示例：与 Minara 聊天

这里有一个完整的工作示例，调用 Minara 的 AI 聊天端点：

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

async function chatWithMinara(query: string) {
  // 1. 设置签名器
  const signer = privateKeyToAccount(
    process.env.EVM_PRIVATE_KEY as `0x${string}`
  );

  // 2. 创建 x402 客户端
  const client = new x402Client();
  registerExactEvmScheme(client, { signer });

  // 3. 包装 fetch
  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  // 4. 发起请求 - SDK 会自动处理支付！
  const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userQuery: query })
  });

  const data = await response.json();
  return data.content;
}

// 用法
const answer = await chatWithMinara("当前 BTC 的价格是多少？");
console.log(answer);
// 输出："BTC 当前交易价格为 $98,450。关键支撑位..."

欲了解更多信息，请查看官方 x402 文档： 买家快速上手

---

2. 手动支付流程（不使用 SDK）

如果你不想使用 SDK，也可以手动处理支付：

步骤 1：发起初始请求

curl -X POST https://x402.minara.ai/x402/chat \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "BTC 的价格是多少？"}'

步骤 2：接收支付挑战

{
  "error": "payment_required",
  "message": "访问此资源需要支付",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0xCF5815e9063FA0b04Be0Cb5C1DB583eeF9ef5fbB",
    "chain": "base"
  }
}

步骤 3：使用钱包付款

使用 MetaMask、Phantom 或任何 Web3 钱包将 USDC 发送到接收地址。

步骤 4：附带支付证明重试

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "BTC 的价格是多少？"}'

步骤 5：获取响应

{
  "content": "BTC 当前交易价格为 $98,450..."
}

---

错误处理

来自 Minara API 的常见错误

402 Payment Required

{ "error": "payment_required" }

→ 正常！SDK 会自动处理此情况。

401 未经授权

{ "error": "unauthorized", "message": "无效的支付响应令牌" }

→ 支付证明无效或已过期。SDK 会重试。

400 错误请求

{ "error": "bad_request", "message": "缺少必需参数：userQuery" }

→ 检查你的请求体是否包含必需字段。

速率限制

x402 端点按钱包地址进行速率限制：

• AI 端点： 每分钟 60 次请求

• 交易端点： 每分钟 30 次请求

如果超过限制：

{
  "error": "rate_limit_exceeded",
  "message": "请求过多。请在 30 秒后重试。",
  "retryAfter": 30
}

---

资源与支持

📚 官方 x402 资源

• x402 协议文档

• 买家快速上手

• x402 GitHub 仓库

• x402 Discord

📦 NPM 包

• @x402/fetch - Fetch 包装器

• @x402/axios - Axios 拦截器

• @x402/evm - EVM 支持（Base、Polygon）

• @x402/svm - Solana 支持

• x402 Python 包

🔍 Minara 专属

• Minara 在 x402scan 上 - 查看所有端点

• Minara API 参考（x402） - API 参考（x402）

API 参考

API 参考（x402）