이미 가진 코인으로 모든 x402 API 결제

x402 엔드포인트는 402 Payment Required로 응답하고 USDC를 요구합니다. ROZO는 Base의 USDC를 요구하는 엔드포인트를 결제합니다. 에이전트가 가진 코인은 다른 체인의 다른 코인일 수 있습니다. 가진 코인으로 ROZO 잔액을 한 번 충전하면 이후 모든 x402 호출이 잔액에서 몇 초 만에 결제됩니다.

명령 세 개

에이전트가 셸 명령을 실행할 수 있다면 이것이 연동의 전부입니다.

# 1. 잔액을 한 번 충전합니다. 일회용 입금 주소를 출력하며, 본인 지갑에서 송금합니다.
npx @rozoai/checkout x402 topup 20 --with usdt-solana

# 2. 유료 엔드포인트를 호출합니다. 402를 읽고 ROZO가 서명한 뒤 결제와 함께 요청을 다시 보냅니다.
npx @rozoai/checkout x402 pay https://api.example.com/v1/search --method POST --body '{"q":"..."}'

# 3. 남은 잔액을 확인합니다.
npx @rozoai/checkout x402 balance

x402 pay가 하는 일

원시 HTTP: 호출 두 번

셸이 없나요? 같은 API를 직접 호출하세요. 에이전트 키는 Authorization: Bearer ak_...로 보냅니다.

# 충전: 선택한 코인의 일회용 입금 주소를 반환합니다.
curl -s -X POST https://apiserver.mpprouter.dev/v1/x402/topup \
  -H 'authorization: Bearer ak_...' -H 'content-type: application/json' \
  -d '{"amount":"20","token":"USDT","chain":"900"}'

# 서명: 402 응답의 "accepts" 목록에서 고른 요건 하나를 보냅니다.
# PAYMENT-SIGNATURE 헤더 값을 반환하며, 그 값으로 요청을 다시 보냅니다.
curl -s -X POST https://apiserver.mpprouter.dev/v1/x402/sign \
  -H 'authorization: Bearer ak_...' -H 'content-type: application/json' \
  -d '{"accepts":[{"scheme":"exact","network":"eip155:8453","amount":"10000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x...","maxTimeoutSeconds":60}],"budget":"0.05","idempotencyKey":"<uuid>"}'

POST /v1/x402/keys는 에이전트 키를 만듭니다(한 번만 표시). GET /v1/x402/balance는 잔액을 반환합니다. 한 결제의 모든 재시도에는 같은 idempotencyKey를 쓰세요.

충전 수단과 실제 결제 수단

두 구간을 일부러 나눠 표시합니다. ROZO에 보내는 것과 판매자가 받는 것.

충전 구간 (사용자 → ROZO)

결제 구간 (ROZO → x402 판매자)

한도와 키

• 건당: 기본 최대 $5. 일일: 기본 최대 $100. 키를 특정 payTo 주소 목록으로 제한할 수도 있습니다.
• 최소 충전: $5. 충전에는 1% 수수료가 붙고, 이후 x402 결제는 판매자가 요구한 금액만 차감됩니다.
• 에이전트 키: 첫 충전 때 ak_로 시작하는 키가 만들어집니다. 한 번만 표시되며 CLI가 ~/.rozo-checkout/x402-key에 본인만 읽을 수 있게 저장합니다. ROZO는 해시만 보관합니다.
• 키가 곧 잔액의 소유권입니다. 프롬프트, 로그, 티켓에 붙여 넣지 마세요. 잃어버리면 새로 만들고 잔액 이전을 위해 연락 주세요.

자주 묻는 질문

왜 먼저 충전해야 하나요?

x402 결제 요건은 1분에서 5분 동안만 유효하지만 체인 간 이동은 더 오래 걸립니다. 이미 준비된 잔액에서 결제해야만 그 시간 안에 응답할 수 있습니다. 충전은 드물게 크게, 결제는 자주 작게 합니다.

제 돈은 어디에 있나요?

ROZO x402 잔액에 있습니다. 자금은 ROZO 지갑에 보관되며 Base의 지갑이 사용자 키를 대신해 결제에 서명합니다. 전체 잔액 합계는 매시간 이 지갑들과 대조됩니다. ROZO는 사용자 본인 지갑의 키를 절대 보관하지 않습니다.

잔액은 어떻게 돌려받나요?

아직 셀프 출금은 지원하지 않습니다. 마스킹한 키(예: ak_...a1b2)와 금액을 hi@rozo.ai로 보내 주시면 원하는 체인으로 돌려드립니다.

ROZO가 제 요청을 보나요?

아니요. 유료 요청은 사용자 기기에서 엔드포인트로 바로 갑니다. ROZO는 서명을 요청받은 결제 요건, 즉 받는 사람, 금액, 네트워크만 봅니다.

판매자는 어떤 네트워크로 결제받나요?

Base의 USDC(eip155:8453), x402 방식 exact입니다. Solana 결제 구간은 추후 지원 예정입니다. 엔드포인트가 Solana만 받으면 CLI가 X402_UNSUPPORTED로 멈추며 아무것도 청구되지 않습니다.