Da intenção à evidência.

Obtenha uma chave API

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

A resposta contém account_id, key_id e um api_key único. Salve-o com segurança. A criação de contas e a emissão de novas chaves criam novas credenciais em cada chamada bem-sucedida; eles não são pontos de extremidade de repetição. As chaves perdidas não podem ser recuperadas por este serviço de desenvolvimento. Emita chaves do agente com escopo definido no console.

1. Registre o pagamento esperado

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

Os valores são strings decimais. Testnet e Mainnet não podem ser misturados. A finalidade e a identidade do Agente são declarações e não prova de autorização. payer_address opcional permite correspondência de remetente; sem ele, a correspondência do pagador não é verificada. Use context_hash para contexto de tarefa confidencial.

2. Pague externamente e envie o hash

Seu próprio código de pagamento Testnet envia o pagamento. Nunca envie ao serviço uma semente de carteira ou chave privada.

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

Uma resposta 202 significa que a verificação está pendente. Tente novamente gravações de auditoria com o mesmo Idempotency-Key e corpo de solicitação após erros de transporte. Reutilizar uma chave com corpo diferente retorna 409.

3. Consulte o estado, baixe e verifique

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

O status do pagamento e o status da âncora são separados. Somente anchor_validated estabelece ancoragem completa. Os relatórios baixados podem estar pendentes; a verificação independente deve então falhar claramente. Use a página Verificar localmente ou execute scripts/verify_report.py do repositório.

Erros e limites de suporte

400: entrada inválida, rede errada ou emissor desabilitado. 401: chave inválida/revogada. 403: escopo insuficiente. 404: registro ausente ou inacessível. 409: conflito de idempotência/transação ou relatório não pronto. 413: corpo muito grande. 429: cota excedida, tente novamente mais tarde. 503: armazenamento/provedor indisponível; tente novamente com segurança.

Interpretação de pagamento suportada: ativos XRP diretos e ativos RLUSD habilitados. Pagamentos parciais bem-sucedidos usam metadados entregues, nunca o valor solicitado. Caminhos complexos, conversões e transações sem pagamento não são suportados. Os tempos limite do nó permanecem pendentes e podem exigir a recuperação do operador da fila de mensagens não entregues.

Limites de prova e privacidade

Relatórios e declarações são privados da sua conta. As provas públicas expõem hashes e informações mínimas de lote/rede. Uma âncora prova a integridade de um registro fornecido, não suas reivindicações, entrega ou cobertura de cada pagamento. A ancoragem da plataforma utiliza um assinante Testnet restrito e dedicado, orçamentos explícitos e uma etapa de habilitação do operador.