Valta Docs

Intents API

See Payout Intents for the state machine and idempotency contract this API implements.

Idempotency key

Any POST /api/v1/spend or POST /api/v1/escrow/* call accepts a caller-supplied key, via either:

Idempotency-Key header (preferred), or
intent_id (or idempotency_key) in the JSON body

bash

curl https://valta.co/api/v1/spend \
  -H 'x-api-key: vlt_live_...' \
  -H 'Idempotency-Key: your-own-uuid' \
  -H 'Content-Type: application/json' \
  -d '{"agent": "agent_123", "amount": 25}'

If omitted, a key is minted server-side — the call still gets a real intent record, but only a caller-persisted key protects against a client that crashed before seeing the response. Every response includes intent_id so you can look up or export the decision later, and replayed: true when the response is a dedup hit rather than a fresh execution.

GET /intents/:intentId/export

Returns a single, self-contained proof document for one intent — its final state, who allowed or blocked it, what it was mutually exclusive with (if anything), its linked domain record, and a hash-chained timeline pulled from the audit log.

bash

curl 'https://valta.co/api/v1/intents/int_a1b2c3.../export?format=json' \
  -H 'x-api-key: vlt_live_...'

Query parameters:

Name	Description
`format`	`json` (default) or `csv`.

Scoped to your own account and the mode (live/test) your API key belongs to — an intent from a different account or the wrong mode returns 404, not another account's data.

Response shape (`format=json`)

json

{
  "intent_id": "int_a1b2c3...",
  "kind": "escrow_dispute",
  "state": "blocked",
  "amount": 500,
  "currency": "USD",
  "allowed_by": null,
  "blocked_reason": "This escrow was already released before the dispute could complete",
  "rail_reference": null,
  "xor_group": "escrow:7",
  "xor_siblings": [
    { "intent_id": "int_d4e5f6...", "kind": "escrow_release", "state": "settled", "blocked_reason": null }
  ],
  "timeline": [
    {
      "at": "2026-08-29T07:20:33.045Z",
      "event_type": "spend_approved",
      "action": "Spend of $500 approved",
      "reasoning": "...",
      "amount": 500,
      "previous_entry_hash": "genesis",
      "entry_hash": "a1b2c3..."
    }
  ],
  "downstream": {
    "escrow_agreement": { "id": 7, "status": "released", "amount": 500 }
  },
  "created_at": "2026-08-29T07:20:33.000Z",
  "updated_at": "2026-08-29T07:20:33.100Z"
}

Response shape (`format=csv`)

A single flat summary row:

intent_id,kind,state,amount,currency,allowed_by,blocked_reason,rail_reference,created_at,updated_at

This is a distinct export surface from the audit API (raw log lines, not scoped to one decision) and the dashboard's compliance export (account-wide, date-ranged) — use this one when you need to hand a single, complete, provable record of one specific financial decision to a counterparty or a compliance review.

SDK equivalent

Not yet built. Use the curl calls above directly until packages/valta-sdk adds an intents resource.