> ## 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는 HTTP 네이티브 결제를 위한 개방형 표준인 [x402 결제 프로토콜](https://x402.org)을 지원합니다.
암호화폐 지갑을 가진 AI Agent는 계정 등록이나 Dashboard 로그인 없이
인증, 크레딧 결제, LLM 요청을 모두 실행할 수 있습니다.

## 세 가지 진입점

ARouter는 Agent가 시작할 수 있는 세 가지 방법을 제공합니다. 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`  | 아니오 | 최대 출력 Token 수              |
| `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는 자금을 보유하지 않습니다.