Rozo의 Agent Merchant API는 그 전제를 없앱니다. EVM EOA는 지갑 서명 한 번으로 가맹점 등록을 하고, 접근이 승인된 뒤 새로운 서명 한 번으로 인보이스 발행과 결제 상태 조회 전용의 Orders 한정 API key를 받습니다. 자금은 서명 주소로 Base의 USDC로 정산되며, 에이전트는 payout_completed가 될 때까지 API를 폴링할 수 있습니다. 이 글에서 전체 흐름을 안내합니다.
에이전트가 실제로 얻는 것
- 지갑에 귀속된 가맹점 계정: 첫 유효 서명으로 생성되고, 반복 서명은 같은 계정을 다시 열 뿐 중복 계정은 절대 만들어지지 않습니다.
- 정산은 서버 측에서 서명 주소의 Base USDC로 고정됩니다. 어떤 API 호출로도 자금의 행선지를 바꿀 수 없습니다.
- Orders 한정 API key: 현행 계약상 자기 계정의 인보이스 생성과 결제 상태 조회만 가능합니다. Admin 자격 증명 발급, 계정 설정 관리, 정산 변경은 할 수 없습니다.
- 인보이스마다 생성되는 결제 링크를 에이전트가 고객에게 공유합니다. 이번 alpha의 EVM 가맹점은 Base의 USDC로 정산을 받습니다.
5단계 루프
- 챌린지 요청: GET /account-nonce?chain=evm&address=$ADDRESS&intent=merchant_onboard. 서버가 서명할 정확한 메시지를 반환하며, 익명 nonce는 거부됩니다.
- 로컬 서명 후 온보딩: POST /account-onboard에 주소·서명·nonce를 보냅니다. 개인키는 에이전트의 실행 환경을 절대 벗어나지 않습니다.
- 접근 신청 후 제한된 자격 증명 발급: 지갑 세션으로 POST /account-credentials/request를 호출하고, 상태 확인을 위한 재요청은 하루 몇 번 이내로 합니다. 승인되면 새로운 credential_issue 챌린지에 서명하고 scope "orders"와 함께 POST /account-credentials를 호출합니다. 발급되는 자격 증명은 Orders 범위이며, Orders 한정 자격 증명으로는 Admin key를 만들 수 없습니다.
- 인보이스 생성: POST /payment-api에 고정된 orderId, Idempotency-Key, 표시 정보, USDC 금액을 보냅니다. destination은 보내지 마세요. 네트워크 오류 후에는 같은 orderId와 멱등 키로 재시도합니다.
- 결제 상태 폴링: Orders key와 고정된 orderId로 payout_completed까지 폴링합니다. webhook이나 이메일 전송이 실패해도 반환된 결제 상태를 기준으로 삼으세요. 응답에 payout 트랜잭션 해시가 있으면 Base에서 추가로 검증할 수 있습니다.
기계가 읽을 수 있는 전체 계약은 https://partners.rozo.ai/llms.txt에 있으며, 에이전트에 그대로 붙여 넣도록 작성되어 있습니다.
권한을 일부러 좁게 만든 이유
자율적으로 움직이는 에이전트에게 결제 자격 증명을 주는 순간이야말로 가장 의심이 필요한 지점입니다. 이 API는 에이전트 key가 유출됐을 때의 피해 반경이 작아지도록 설계되었습니다.
- Orders 한정 key는 다른 key를 만들 수 없고 정산도 바꿀 수 없으며, 조회 범위는 자기 계정으로 한정됩니다. 지갑으로 발급한 자격 증명의 목록 조회와 폐기에는 목적이 지정된 새로운 지갑 서명이 필요합니다.
- 자격 증명 발급에는 새로운 지갑 서명이 필수입니다. 훔친 세션 토큰만으로는 key를 만들 수 없습니다.
- 모든 챌린지는 일회용이고 목적이 고정되며, 서버가 지정한 만료 시각을 가집니다.
- 수취 주소는 서명 주소와 같으며 서버 측에서 강제됩니다. 유출된 Orders key로는 설정된 정산 주소를 바꿀 수 없지만, 원치 않는 인보이스 생성과 결제 상태 노출은 가능하므로 새로운 지갑 증명으로 즉시 폐기하세요.
접근 권한 얻기 (alpha)
자격 증명 프로그램은 alpha 동안 초대제로 운영됩니다. 온보딩 후 에이전트는 POST /account-credentials/request를 호출하고, 상태 확인을 위한 재요청은 하루 몇 번 이내로 합니다. 승인은 Rozo 측 사람이 결정하지만 이메일이나 DM은 필요 없습니다. 현재 자격 증명·인보이스 루프는 Base에서 USDC로 정산하는 EVM EOA를 지원합니다. Solana와 Stellar EOA도 온보딩해 각자의 서명 주소 체인에서 USDC를 받을 수 있지만, 이 자격 증명 루프의 대상은 아닙니다.
이번 alpha에서는 EVM 컨트랙트 지갑을 지원하지 않으며, 지갑 전용 계정에는 복구 수단이 없습니다. 서명 키를 잃어버리면 Rozo는 해당 가맹점을 복구할 수 없고 수동 소유권 이전도 제공하지 않습니다.
https://partners.rozo.ai/agent 에서 시작하세요.