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

# x402 Agent 決済

> 暗号ウォレットを持つ AI Agent が自動的にクレジットをチャージして認証できます — 登録不要、Dashboard 不要、完全自律。

ARouter は [x402 決済プロトコル](https://x402.org)（HTTP ネイティブ決済のオープン標準）をサポートしています。
暗号ウォレットを持つ AI Agent は、認証、クレジットの支払い、LLM リクエストを
アカウント登録や Dashboard ログインなしで実行できます。

## 3 つのエントリーポイント

ARouter は Agent が開始するための 3 つの方法を提供しています。API Key ユーザーとウォレットユーザーは、それぞれ独立した長期パスを辿ります：

| エントリーポイント      | 認証方法                                 | ユースケース                                              |
| -------------- | ------------------------------------ | --------------------------------------------------- |
| **標準 x402 決済** | `PAYMENT-SIGNATURE` ヘッダーのみ           | 任意の x402 クライアント — 最初のウォレット決済でアカウントを登録しウォレット JWT を返す |
| **SIWx 認証**    | `SIGN-IN-WITH-X` ヘッダー                | ウォレット所有権を証明 → ウォレット JWT を取得（決済不要）                   |
| **API Key**    | `Authorization: Bearer lr_live_xxxx` | 既存の API Key ユーザー — 残高不足で `403` を返し、x402 自動チャージは行わない |

<Info>
  標準 x402 モードは**任意の x402 対応ツール**で動作します — `@x402/fetch`、`awal`、MCP ウォレット、Chrome 拡張機能。
  ARouter SDK は不要です。
</Info>

***

## 仕組み

### 標準 x402（任意の x402 クライアント）

最もシンプルなエントリーポイント。USDC を持つ任意のウォレットで即座に LLM リクエストが可能です：

```mermaid theme={null}
sequenceDiagram
    participant Wallet as 任意のウォレット
    participant Client as x402 クライアント (@x402/fetch)
    participant GW as ARouter ゲートウェイ
    participant Chain as Base / Solana

    Client->>GW: POST /v1/chat/completions（認証なし）
    GW-->>Client: 402 + PAYMENT-REQUIRED
    Client->>Wallet: USDC 決済に署名（ガスレス EIP-3009）
    Wallet-->>Client: 署名済み決済
    Client->>GW: リトライ + PAYMENT-SIGNATURE
    GW->>Chain: 検証 & 決済
    GW-->>Client: 200 OK + PAYMENT-RESPONSE(jwt)
    Note over Client: 将来のリクエスト用にウォレット JWT を保存
```

1. **API Key なし**でリクエストを送信 — ゲートウェイが決済オプション付きの **HTTP 402** を返す。
2. x402 クライアントが USDC 決済に署名（EIP-3009 経由でガスレス）。
3. `PAYMENT-SIGNATURE` ヘッダーを付けてリトライ。
4. ゲートウェイが検証、決済、アカウント作成を行いレスポンスを返す。
5. `PAYMENT-RESPONSE` ヘッダーに将来のウォレット認証リクエスト用の `jwt` 拡張フィールドが含まれる。

### SIWx 認証（ウォレットサインイン）

先に支払わずにウォレット所有権を証明してウォレット JWT を取得します：

```mermaid theme={null}
sequenceDiagram
    participant Wallet as 任意のウォレット
    participant Client as クライアント
    participant Auth as POST /v1/x402/auth

    Client->>Wallet: CAIP-122 メッセージに署名
    Wallet-->>Client: 署名
    Client->>Auth: SIGN-IN-WITH-X ヘッダー
    Auth-->>Client: {"jwt": "eyJ..."}
    Note over Client: ウォレットリクエストに Bearer JWT を使用
```

SIWx は [CAIP-122 標準](https://chainagnostic.org/CAIPs/caip-122) に従います — QuickNode やその他の x402 対応サービスと同じプロトコルです。

### API Key ユーザー

既存の API Key ユーザーは標準の ARouter API Key フローを引き続き使用します：

```mermaid theme={null}
sequenceDiagram
    participant Agent as AI Agent + ウォレット
    participant GW as ARouter ゲートウェイ
    participant Chain as Base / Solana

    Agent->>GW: POST /v1/chat/completions（Bearer token）
    GW-->>Agent: 403 クレジット不足
    Note over Agent: Dashboard / Stripe / 従来の請求でチャージ
```

***

## サポートネットワーク

| ネットワーク               | CAIP-2 識別子                                | Token |
| -------------------- | ----------------------------------------- | ----- |
| Base メインネット          | `eip155:8453`                             | USDC  |
| Base Sepolia（テストネット） | `eip155:84532`                            | USDC  |
| Solana メインネット        | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | USDC  |
| Solana Devnet        | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | USDC  |

## ウォレット互換性

すべてのウォレットが使用可能 — **秘密鍵のエクスポート不要**：

| ウォレット                 | 決済 (EIP-3009) | 認証 (SIWx) | 秘密鍵が必要？       |
| --------------------- | ------------- | --------- | ------------- |
| MetaMask              | ✓             | ✓         | いいえ           |
| Coinbase Wallet       | ✓             | ✓         | いいえ           |
| Coinbase Agent Wallet | ✓             | ✓         | いいえ (CDP API) |
| Phantom (Solana)      | ✓             | ✓         | いいえ           |
| ローカル秘密鍵               | ✓             | ✓         | はい            |

***

## SDK の使用方法

### 標準 x402（ARouter SDK 不要）

Coinbase の公式 `@x402/fetch` を直接使用します：

```typescript theme={null}
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const paidFetch = wrapFetchWithPayment(fetch, client);

const resp = await paidFetch("https://api.arouter.ai/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/gpt-5.4",
    messages: [{ role: "user", content: "Hello" }],
  }),
});
```

### SIWx 認証（ウォレット JWT の取得）

#### Node.js SDK

```typescript theme={null}
import { ARouter, authenticateWithSIWx } from "@arouter/sdk";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

const { jwt } = await authenticateWithSIWx(
  "https://api.arouter.ai",
  { address: account.address, signMessage: (msg) => account.signMessage({ message: msg }) },
);

const client = new ARouter({ baseURL: "https://api.arouter.ai", apiKey: jwt });
```

#### Go SDK

```go theme={null}
import arouter "github.com/arouter-ai/arouter-go"

signer := arouter.NewEvmWalletSigner(privateKey)
result, err := arouter.AuthenticateWithSIWx(ctx, "https://api.arouter.ai", signer, nil)

client := arouter.NewClient("https://api.arouter.ai", result.JWT)
```

### ARouter SDK + 自動決済（高頻度使用向け推奨）

#### Go SDK — EVM (Base)

```go theme={null}
import (
    "github.com/ethereum/go-ethereum/crypto"
    arouter "github.com/arouter-ai/arouter-go"
)

key, _ := crypto.HexToECDSA("your-private-key-hex")

client := arouter.NewClient(
    "https://api.arouter.ai",
    "",  // API Key 不要
    arouter.WithX402CoinbasePayment(key),
)
```

`WithX402CoinbasePayment` は JWT キャッシュ付きのウォレット x402 決済を設定します：

* 最初の成功した決済で `PAYMENT-RESPONSE` 内にウォレット JWT が返される
* 以降のリクエストは `Bearer <jwt>` を使用
* `401` で SIWx 再認証をトリガー
* `402` で x402 決済をトリガー

#### Go SDK — Solana

```go theme={null}
solanaKey := ed25519.PrivateKey(yourKeyBytes)
client := arouter.NewClient("https://api.arouter.ai", "",
    arouter.WithX402SolanaPayment(solanaKey),
)
```

#### Node.js SDK — EVM (Base)

```typescript theme={null}
import { ARouter, withX402EvmPayment } from "@arouter/sdk";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = withX402EvmPayment(
  new ARouter({ baseURL: "https://api.arouter.ai", apiKey: "" }),
  signer,
);
```

#### Node.js SDK — デュアルチェーン（EVM + Solana）

```typescript theme={null}
import { ARouter, withX402Payment } from "@arouter/sdk";

const client = withX402Payment(
  new ARouter({ baseURL: "https://api.arouter.ai", apiKey: "" }),
  {
    evm: { signer: evmAccount },
    solana: { signer: solanaSigner },
  },
);
```

### CLI ツール向け GET エンドポイント

POST ボディを送信できない x402 CLI ツール（`awal` など）向け：

```
GET /v1/x402/chat?model=openai/gpt-5.4&message=Hello&system=Be+brief&max_tokens=100
```

| パラメータ         | 必須  | 説明                      |
| ------------- | --- | ----------------------- |
| `model`       | はい  | モデル名、例：`openai/gpt-5.4` |
| `message`     | はい  | ユーザーメッセージテキスト           |
| `system`      | いいえ | システムプロンプト               |
| `max_tokens`  | いいえ | 最大出力トークン数               |
| `temperature` | いいえ | 温度パラメータ                 |
| `stream`      | いいえ | ストリーミングには `true` を設定    |

***

## 決済ヘッダー

| ヘッダー                | 方向            | 説明                                                        |
| ------------------- | ------------- | --------------------------------------------------------- |
| `PAYMENT-REQUIRED`  | サーバー → クライアント | Base64 エンコードされた決済オプション（金額、ウォレット、ネットワーク）。                  |
| `PAYMENT-SIGNATURE` | クライアント → サーバー | Base64 エンコードされた署名済み決済ペイロード。                               |
| `SIGN-IN-WITH-X`    | クライアント → サーバー | Base64 エンコードされた SIWx 認証証明。                                |
| `PAYMENT-RESPONSE`  | サーバー → クライアント | Base64 エンコードされた決済結果。ARouter がウォレットユーザー向けに `jwt` フィールドを追加。 |

## クレジットの仕組み

* x402 決済は**クレジット**としてテナント残高に入金されます — Stripe および Helio 決済と同じプールを使用。
* すべての x402 トランザクションは**請求**ページのトランザクション履歴に `x402_topup` 参照タイプで表示されます。
* 残高がチャージされた後、ゲートウェイは通常通りリクエストごとにクレジットを差し引きます。
* ウォレットユーザーはテナント単位で課金され、ウォレット JWT で認証され、生の API Key を公開せずに SIWx で再認証できます。

## セキュリティ

* **標準 x402 プロトコル**: Coinbase の公式 x402 SDK を使用して検証と決済を行います。
* **Facilitator 検証**: 決済は [x402 Facilitator](https://x402.org) によって暗号学的に検証されてからクレジットが付与されます。
* **ガスレス決済**: EIP-3009（TransferWithAuthorization）— ユーザーが署名し、Facilitator がオンチェーンで送信。
* **金額上限**: 予期せぬ高額請求を防ぐため、単一決済に上限を設定。
* **冪等性**: 各決済ペイロードには一意の nonce があります — 同じ署名の再利用は不可。
* **SIWx 標準**: 認証は [CAIP-122](https://chainagnostic.org/CAIPs/caip-122) に従い、EIP-4361（EVM）および SIWS（Solana）メッセージ形式をサポート。
* **監査証跡**: すべての x402 チャージは Stripe/Helio 決済とともにトランザクション履歴に記録されます。
* **非カストディアル**: USDC は受信ウォレットに直接転送されます。Facilitator は資金を保有しません。