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.
ARouter는 HTTP 네이티브 결제를 위한 개방형 표준인 x402 결제 프로토콜을 지원합니다.
암호화폐 지갑을 가진 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 자동 충전 없음 |
표준 x402 모드는 모든 x402 호환 도구에서 작동합니다 — @x402/fetch, awal, MCP 지갑, Chrome 확장 프로그램.
ARouter SDK가 필요하지 않습니다.
작동 방식
표준 x402 (모든 x402 클라이언트)
가장 단순한 진입점. USDC를 보유한 모든 지갑으로 즉시 LLM 요청 가능:
- API Key 없이 요청 전송 — 게이트웨이가 결제 옵션과 함께 HTTP 402를 반환합니다.
- x402 클라이언트가 USDC 결제에 서명 (EIP-3009를 통한 가스리스).
PAYMENT-SIGNATURE 헤더를 포함하여 재시도.- 게이트웨이가 검증, 결제, 계정 생성 후 응답을 반환합니다.
PAYMENT-RESPONSE 헤더에 향후 지갑 인증 요청을 위한 jwt 확장 필드가 포함됩니다.
SIWx 인증 (지갑 로그인)
먼저 결제하지 않고 지갑 소유권을 증명하여 지갑 JWT를 획득:
SIWx는 CAIP-122 표준을 따릅니다 — QuickNode 및 기타 x402 지원 서비스와 동일한 프로토콜.
API Key 사용자
기존 API Key 사용자는 표준 ARouter API Key 플로우를 계속 사용합니다:
지원 네트워크
| 네트워크 | 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를 직접 사용합니다:
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
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
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)
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
solanaKey := ed25519.PrivateKey(yourKeyBytes)
client := arouter.NewClient("https://api.arouter.ai", "",
arouter.WithX402SolanaPayment(solanaKey),
)
Node.js SDK — EVM (Base)
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)
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를 통해 암호학적으로 검증된 후 크레딧이 부여됩니다.
- 가스리스 결제: EIP-3009 (TransferWithAuthorization) — 사용자가 서명하고 Facilitator가 온체인에 제출합니다.
- 금액 상한: 예상치 못한 대규모 청구를 방지하기 위해 단일 결제에 상한 적용.
- 멱등성: 각 결제 페이로드에는 고유한 nonce가 있습니다 — 동일한 서명은 재사용 불가.
- SIWx 표준: 인증은 CAIP-122를 따르며 EIP-4361 (EVM) 및 SIWS (Solana) 메시지 형식을 지원합니다.
- 감사 추적: 모든 x402 충전은 Stripe/Helio 결제와 함께 트랜잭션 내역에 기록됩니다.
- 비수탁: USDC는 수신 지갑으로 직접 전송됩니다. Facilitator는 자금을 보유하지 않습니다.
