이 가이드는 Solana 요청 하나를 예로 x402의 흐름을 따라갑니다. 가격을 확인하고 결제한 뒤, 정산 영수증과 함께 응답을 받기까지의 과정입니다. 나머지 15개 체인도 각자의 경로에서 같은 방식으로 동작합니다.
Solana의 USDC, 또는 Base의 USDC나 EURC가 들어 있는 지갑과 x402 클라이언트가 필요합니다. x402 클라이언트는 402 응답을 읽고, 지갑에서 결제에 서명한 뒤 그 결제와 함께 요청을 다시 보내는 소프트웨어입니다. x402 클라이언트에 대해서는
x402.org의 x402 문서를 참고하세요.
1. 요청 보내기
결제 없이 RPC 요청을 보내세요.
curl -i https://x402.erpc.global/v1/solana-mainnet \
--header 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
curl -i https://x402.erpc.global/v1/solana-mainnet \
--header 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
응답은 402 Payment Required입니다. 헤더에 메서드와 가격이 들어 있습니다.
HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001
HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001
본문의 accepts에는 이 요청을 결제할 수 있는 스테이블코인마다 결제 옵션이 하나씩 나열됩니다. amount는 스테이블코인의 최소 단위로 나타낸 금액이므로, 1000은 0.001 USDC 또는 0.001 EURC입니다.
{
"error": { "code": "payment_required", "message": "Payment required", "request_id": "…" },
"x402Version": 2,
"accepts": [
{ "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "1000", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", … },
{ "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", … },
{ "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", … }
],
"pricing": { "methods": ["getSlot"], …, "weight": 1000, "rawWeight": 42, …, "price": "$0.001", … },
…
}
{
"error": { "code": "payment_required", "message": "Payment required", "request_id": "…" },
"x402Version": 2,
"accepts": [
{ "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "1000", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", … },
{ "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", … },
{ "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", … }
],
"pricing": { "methods": ["getSlot"], …, "weight": 1000, "rawWeight": 42, …, "price": "$0.001", … },
…
}
2. x402 클라이언트로 결제하기
402 응답을 x402 클라이언트에 넘기세요. 클라이언트는 지갑으로 결제할 수 있는 옵션을 고르고, 그 금액의 결제에 서명한 뒤 X-Payment 헤더에 넣을 값으로 인코딩합니다. 이 결제에는 네트워크 수수료용 SOL이나 ETH가 필요 없습니다.
3. 결제를 붙여 요청 다시 보내기
X-Payment 헤더에 결제를 넣어 같은 본문을 다시 보내세요.
curl -i https://x402.erpc.global/v1/solana-mainnet \
--header 'Content-Type: application/json' \
--header 'X-Payment: <PAYMENT_PAYLOAD>' \
--data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
curl -i https://x402.erpc.global/v1/solana-mainnet \
--header 'Content-Type: application/json' \
--header 'X-Payment: <PAYMENT_PAYLOAD>' \
--data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
본문은 바꾸지 마세요. 가격은 본문을 기준으로 계산되므로, 바꾼 본문의 가격이 달라지면 결제가 그 가격과 맞지 않게 되어 price_mismatch가 반환됩니다.
결제가 검증되고 정산되면 RPC 응답이 돌아오고, 정산 영수증은 X-Payment-Response 헤더에 들어 있습니다.
HTTP/2 200
x-payment-response: <RECEIPT>
HTTP/2 200
x-payment-response: <RECEIPT>
{ "jsonrpc": "2.0", "id": 1, "result": … }
{ "jsonrpc": "2.0", "id": 1, "result": … }
결제 하나는 요청 하나에만 쓸 수 있습니다. 같은 결제를 다시 보내면 402 payment_invalid 또는 409 duplicate_payment로 거부되고, 요청은 다시 전달되지 않습니다.
응답
x402.erpc.global이 결제를 요청하기 전에 오류로 응답한 요청에는 요금이 들지 않습니다.
Solana에서는 큰 프로그램에 필터 없이 보내는 getProgramAccounts처럼 읽는 데이터가 너무 많은 호출에 대해, 결제를 요청하기 전에 HTTP 200과 JSON-RPC 오류를 반환하므로 요금이 들지 않습니다.
다음 단계
