Rozo の Agent Merchant API はその前提を取り除きます。EVM の EOA はウォレット署名 1 回でマーチャントとして登録でき、アクセスが承認された後、もう 1 回の新しい署名で、インボイス発行と支払いステータス読み取り専用の 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 を呼び、ステータス確認のための再送は 1 日数回までにします。承認後、新しい 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 を呼び、ステータス確認の再送は 1 日数回までにします。承認は Rozo 側の人間が判断しますが、メールやダイレクトメッセージは不要です。現在の資格情報とインボイス発行のループは、Base 上で USDC 決済する EVM の EOA をサポートします。Solana と Stellar の EOA も登録してそれぞれの署名アドレスのチェーンで USDC を受け取れますが、この資格情報ループの対象外です。
この alpha では EVM のコントラクトウォレットは未対応で、ウォレットのみのアカウントに復旧手段はありません。署名鍵を失うと、Rozo はそのマーチャントを復元できず、手動での所有権移転も行いません。
https://partners.rozo.ai/agent から始めてください。