Documentation Index Fetch the complete documentation index at: https://docs.usemandate.io/llms.txt
Use this file to discover all available pages before exploring further.
Transactions are created automatically by the policy engine and payment verification flow — you never create them directly. Each transaction captures the full context of a payment attempt: which agent requested it, which mandate governed it, which merchant received it, the amount and resource involved, and the final outcome. Use this endpoint to build dashboards, reconcile charges, or investigate policy decisions.
List transactions Returns transactions for your account, ordered by creation date descending. Use query parameters to narrow results by agent, mandate, or status. Results are limited to 200 records per request — use repeated filtered queries to page through larger datasets.
Query parameters Filter to transactions initiated by this agent.
Filter to transactions charged against this mandate.
Filter by transaction status. One of: pending, approved, denied, paid, failed, refunded.
Maximum number of results to return. Minimum 1, maximum 200.
curl "https://api.kya.dev/v1/transactions?agent_id=agent_abc123&status=paid&limit=25" \ --header "Authorization: Bearer ky_sand_••••••••••••••••"
Response 200 Array of transaction objects, ordered by created_at descending. Show Transaction object fields
Unique transaction identifier.
The agent that initiated this transaction.
The mandate governing this transaction.
Transaction amount as a decimal string.
Currency code, e.g. "USDC".
The URL of the resource that was purchased or attempted.
Optional category label passed during policy evaluation, e.g. "data".
Transaction outcome. One of: pending, approved, denied, paid, failed, refunded.
true if this transaction was created under a sandbox API key.
ISO 8601 creation timestamp.
ISO 8601 timestamp of the last status update.
{ "transactions" : [ { "id" : "transaction_ghi789" , "agent_id" : "agent_abc123" , "mandate_id" : "mandate_xyz789" , "amount" : "0.100000" , "currency" : "USDC" , "resource_url" : "https://api.example.com/data/companies/AAPL" , "resource_category" : "data" , "status" : "paid" , "sandbox" : true , "created_at" : "2024-01-15T10:30:00Z" , "updated_at" : "2024-01-15T10:30:01Z" }, { "id" : "transaction_jkl012" , "agent_id" : "agent_abc123" , "mandate_id" : "mandate_xyz789" , "amount" : "1.000000" , "currency" : "USDC" , "resource_url" : "https://api.example.com/data/companies/GOOG" , "resource_category" : "data" , "status" : "denied" , "sandbox" : true , "created_at" : "2024-01-15T10:25:00Z" , "updated_at" : "2024-01-15T10:25:00Z" } ] }
Transaction statuses Status Description pendingPolicy evaluation is in progress. Short-lived — resolves to approved or denied immediately. approvedPolicy approved the payment. Awaiting proof verification to transition to paid. deniedPolicy rejected the payment. See the audit log for the reason_code. paidPayment proof was verified and the mandate budget has been charged. failedAn unexpected error occurred during policy evaluation or verification. refundedReserved for future use.
