Dalle intenzioni alle prove.

Ottieni una chiave API

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

La risposta contiene account_id, key_id e un api_key una tantum. Salvalo in modo sicuro. La creazione dell'account e l'emissione di nuove chiavi creano nuove credenziali per ogni chiamata andata a buon fine; non sono endpoint di riproduzione. Le chiavi perse non possono essere recuperate da questo servizio di sviluppo. Emettere chiavi dell'agente con ambito dalla console.

1. Registrare il pagamento previsto

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

Gli importi sono stringhe decimali. Testnet e Mainnet non possono essere mischiati. Lo scopo e l'identità dell'Agente sono dichiarazioni, non prova di autorizzazione. payer_address opzionale consente la corrispondenza del mittente; senza di esso, la corrispondenza del pagatore non viene verificata. Utilizzare context_hash per contesti di attività sensibili.

2. Paga esternamente, quindi invia l'hash

Il tuo codice di pagamento Testnet invia il pagamento. Non inviare mai al servizio un seed di portafoglio o una chiave privata.

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

Una risposta 202 significa che la verifica è in sospeso. Riprovare la scrittura di controllo con lo stesso Idempotency-Key e richiedere il corpo dopo gli errori di trasporto. Riutilizzare una chiave con un corpo diverso restituisce 409.

3. Controlla lo stato, scarica e verifica

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

Lo stato del pagamento e lo stato di ancoraggio sono separati. Solo anchor_validated stabilisce l'ancoraggio completo. I report scaricati potrebbero essere in sospeso; la verifica indipendente deve quindi fallire chiaramente. Utilizza la pagina Verifica localmente o esegui scripts/verify_report.py dal repository.

Errori e limiti del supporto

400: input non valido, rete sbagliata o emittente disabilitato. 401: chiave non valida/revocata. 403: portata insufficiente. 404: registrazione assente o inaccessibile. 409: idempotenza/conflitto transazione o report non pronto. 413: corpo troppo grande. 429: quota superata, riprovare più tardi. 503: storage/provider non disponibile; riprovare in tutta sicurezza.

Interpretazione dei pagamenti supportata: XRP diretto e asset RLUSD abilitati. I pagamenti parziali riusciti utilizzano i metadati consegnati, mai l'importo richiesto. Percorsi complessi, transazioni di conversione e non di pagamento non sono supportati. I timeout del nodo rimangono in sospeso e potrebbero richiedere il ripristino dell'operatore dalla coda dei messaggi non recapitati.

Limiti di prova e privacy

Rapporti e dichiarazioni sono private sul tuo account. Le prove pubbliche espongono hash e informazioni minime su batch/rete. Un'ancora dimostra l'integrità di un documento fornito, non le sue richieste, la consegna o la copertura di ogni pagamento. L'ancoraggio della piattaforma utilizza un firmatario Testnet limitato dedicato, budget espliciti e una fase di abilitazione dell'operatore.