从意图到证据。

获取 API 密钥

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

响应包含 account_id、key_id 和一次性 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"}'

金额是十进制字符串。测试网和主网不能混合。目的和智能体人身份是声明，而不是授权证明。可选payer_address实现发送者匹配；如果没有它，则不会检查付款人匹配。对于敏感任务上下文，请使用 context_hash。

2.外部支付，然后提交hash

您自己的测试网付款代码会发送付款。切勿向服务发送钱包助记词或私钥。

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 资产。成功的部分付款按实际到账元数据核验，不能使用请求中的 Amount。暂不支持复杂路径、兑换或非 Payment 交易。节点超时会保持待处理，可能需要运维人员恢复死信队列中的任务。

证明和隐私边界

报告与声明仅对你的账户可见。公开证明只包含哈希和最少的批次、网络信息。存证只能证明给定记录的完整性，不能证明声明属实、已经履约或涵盖所有付款。平台使用专用且受限的测试网签名账户、明确的预算，并需由运维人员启用存证。