From intent to evidence.

Get an API Key

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

The response contains account_id, key_id and a one-time api_key. Save it securely. Account creation and new key issuance create fresh credentials on every successful call; they are not replay endpoints. Lost keys cannot be recovered by this development service. Issue scoped Agent keys from the console.

1. Record the expected payment

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"}'

Amounts are decimal strings. Testnet and Mainnet cannot be mixed. Purpose and Agent identity are declarations, not proof of authorization. Optional payer_address enables sender matching; without it, payer matching is not checked. Use context_hash for sensitive task context.

2. Pay externally, then submit the hash

Your own Testnet payment code sends the payment. Never send the service a wallet seed or private key.

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>"}'

A 202 response means verification is pending. Retry audit writes with the same Idempotency-Key and request body after transport errors. Reusing a key with a different body returns 409.

3. Check status, download and independently verify

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

Payment status and anchor status are separate. Only anchor_validated establishes completed anchoring. Downloaded reports may be pending; independent verification must then fail clearly. Use the Verify page locally or run scripts/verify_report.py from the repository.

Errors and support boundaries

400: invalid input, wrong network or disabled issuer. 401: invalid/revoked key. 403: insufficient scope. 404: absent or inaccessible record. 409: idempotency/transaction conflict or report not ready. 413: body too large. 429: quota exceeded, retry later. 503: storage/provider unavailable; retry safely.

Supported payment interpretation: direct XRP and enabled RLUSD assets. Successful partial payments use delivered metadata, never the requested Amount. Complex paths, conversion and non-Payment transactions are unsupported. Node timeouts stay pending and may require operator recovery from the dead-letter queue.

Proof and privacy boundaries

Reports and declarations are private to your account. Public proofs expose hashes and minimal batch/network information. An anchor proves the integrity of a supplied record, not its claims, delivery or coverage of every payment. Platform anchoring uses a dedicated restricted Testnet signer, explicit budgets and an operator enablement step.