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("Request failed: %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 Unauthorized

{ "error": "unauthorized", "message": "無効な支払い応答トークン" }

→ 支払い証明が無効または期限切れです。SDKが再試行します。

400 Bad Request

{ "error": "bad_request", "message": "必須パラメータが欠落しています: userQuery" }

→ リクエストボディに必須フィールドがあるか確認してください。

レート制限

x402エンドポイントはウォレットアドレスごとにレート制限があります：

• AIエンドポイント: 1分あたり60リクエスト

• トレーディングエンドポイント: 1分あたり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固有

• x402scanのMinara - すべてのエンドポイントを表示

• Minara APIリファレンス（x402） - APIリファレンス（x402）

APIリファレンス

APIリファレンス（x402）