意図から証拠へ。

API キーを取得する

curl -X POST https://agenttrail.online/api/v1/accounts \
  -H 'Content-Type: application/json' -d '{}'

応答には、account_id、key_id、および 1 回限りの api_key が含まれます。安全に保存してください。アカウントの作成と新しいキーの発行により、呼び出しが成功するたびに新しい認証情報が作成されます。これらは再生エンドポイントではありません。紛失したキーは、この開発サービスでは回復できません。コンソールからスコープ指定されたエージェント キーを発行します。

1. 支払い予定額を記録する

export AUDIT_KEY='<save the one-time API key securely>'
curl -X POST https://agenttrail.online/api/v1/audit/intents \
  -H "Authorization: Bearer $AUDIT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-stable-intent-reference' \
  -d '{"agent_id":"research-01","network":"xrpl-testnet", "asset":{"type":"native","currency":"XRP"},"expected_amount":"1","recipient":"<recipient classic address>","purpose":"purchase_market_data"}'

金額は 10 進数の文字列です。テストネットとメインネットを混在させることはできません。目的とエージェントの身元は宣言であり、承認の証拠ではありません。オプションの payer_address により、送信者の照合が有効になります。これがないと、支払者の照合はチェックされません。機密性の高いタスク コンテキストには context_hash を使用します。

2. 外部で支払い、ハッシュを送信します

独自の Testnet 支払いコードによって支払いが送信されます。サービスにウォレット シードや秘密キーを送信しないでください。

curl -X POST https://agenttrail.online/api/v1/audit/transactions \
  -H "Authorization: Bearer $AUDIT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-stable-payment-reference' \
  -d '{"audit_id":"<audit_id>","network":"xrpl-testnet","tx_hash":"<64-character hash>"}'

202 応答は検証が保留中であることを意味します。トランスポート エラーの後に、同じ Idempotency-Key とリクエスト本文を使用して監査書き込みを再試行します。ボディが異なるキーを再利用すると 409 が返されます。

3. 状態確認、ダウンロード、独立検証

curl -H "Authorization: Bearer $AUDIT_KEY" \
  https://agenttrail.online/api/v1/audit/records/<audit_id>
curl -H "Authorization: Bearer $AUDIT_KEY" \
  https://agenttrail.online/api/v1/audit/records/<audit_id>/report -o audit.json

支払いステータスとアンカーステータスは別です。 anchor_validated のみが完了したアンカリングを確立します。ダウンロードされたレポートは保留中の場合があります。その場合、独立した検証は明らかに失敗するはずです。 「検証」ページをローカルで使用するか、リポジトリから scripts/verify_report.py を実行します。

エラーとサポートの境界

400: 無効な入力、間違ったネットワーク、または無効な発行者。 401: キーが無効/取り消されました。 403: 範囲が不十分です。 404: レコードが存在しないかアクセスできません。 409: 冪等性/トランザクションの競合、またはレポートの準備ができていません。 413: 本体が大きすぎます。 429: クォータを超えました。後で再試行してください。 503: ストレージ/プロバイダーが利用できません。安全に再試行してください。

サポートされている支払い解釈: 直接 XRP および有効な RLUSD アセット。部分支払いが成功すると、要求された金額ではなく、配信されたメタデータが使用されます。複雑なパス、変換および非支払いトランザクションはサポートされていません。ノードのタイムアウトは保留されたままになるため、オペレータによる配信不能キューからの回復が必要になる場合があります。

証拠とプライバシーの境界

レポートと宣言はあなたのアカウントに対して非公開です。公開証明では、ハッシュと最小限のバッチ/ネットワーク情報が公開されます。アンカーは、提供された記録の完全性を証明するものであり、その請求、配達、またはすべての支払いの範囲を証明するものではありません。プラットフォームのアンカーリングでは、専用の制限付きテストネット署名者、明示的な予算、およびオペレーターの有効化ステップを使用します。