Endpoint

The one endpoint. Your wallet is your account: every call carries a CAIP-122 sign-in in the SIGN-IN-WITH-X header (domain api.kviria.com, URI https://api.kviria.com, a fresh single-use nonce per request). The x-kviria-agent header (or ?agent=) is a namespace label that isolates your agent’s context — it is not a secret.

POST https://api.kviria.com/v1/agent
Content-Type: application/json
Body limit: 16 KB

The authoritative wire schema (JSON Schema, MCP-ready) lives at kviria.com/tool-definition.json. Your first 50 turns each day are free; beyond that, pay per turn — see Payments. The SIGN-IN-WITH-X header is a CAIP-122 payload, signed by your wallet and base64-encoded. Build it per request — every nonce is single-use. 1. Build the payload:

{
  "domain": "api.kviria.com",
  "address": "0xYourWalletAddress",
  "uri": "https://api.kviria.com",
  "version": "1",
  "chainId": "eip155:8453",
  "type": "eip191",
  "nonce": "a fresh random value",
  "issuedAt": "2026-09-09T12:00:00.000Z"
}

2. Sign the EIP-191 message it describes (the standard SIWE text — domain, address, URI, version, Chain ID: 8453, Nonce, Issued At lines) with your wallet’s personal-sign. 3. Add the signature, base64 the JSON, send it:

curl -X POST "https://api.kviria.com/v1/agent?agent=my-agent" \
  -H "Content-Type: application/json" \
  -H "SIGN-IN-WITH-X: $SIWX" \
  -d '{ ... }'

If you use the x402 TypeScript SDKs, @x402/extensions/sign-in-with-x provides the helpers (createSIWxMessage, signEVMMessage, encodeSIWxHeader) so the three steps are two lines of code.

Request body

Field	Type	Notes
`transcript`	string	The user’s raw words - or `intent`, never both
`intent`	object	The structured meaning your LLM mapped (see below)
`anchor`	object	The user’s current position `{lat, lng}` - required
`candidates`	array	Echo the previous candidates verbatim
`references`	array	Previously resolved `{gers, name}`, most-recent first (max 5)
`frame`	object	The last street context
`rangeM`	number	Search radius, 50-1000 (default 100)
`confirmation`	string	`"on"` (default) or `"off"` - the confirm gate

The structured intent

Your agent can do the mapping itself and skip the transcript entirely - zero model calls on Kviria’s side, fully deterministic. The actions: search, find, select, confirm, neighbors, across, along, at_address, street_zoom, street_end, near

{
  "intent": { "action": "search", "categoryAny": ["cafe"] },
  "anchor": { "lat": 37.76326, "lng": -122.4152 }
}

Anchors resolve from Kviria’s own data only: a ref (a previous response’s id), a name exactly as returned, an index into the echoed candidates, or at coordinates. Invalid intents return a strict 400 that names the bad field - fix it and retry once.

Response

Decision	Meaning
`resolved`	One match, final
`confirm`	One candidate, waiting for the user’s yes/no
`candidates`	Several matches
`notFound`	No match (may carry the absent `category`)
`clarify`	The reference was too vague

target carries the outcome: gers (stable id), name, category, location {lat, lng}, distanceM - and address: {number, street} when the match is a door. A door resolves as resolved without the confirm gate: an exact address verifies itself. evidence is the audit trail - see Determinism & evidence.

Getting Started

How it works

API

Reference

Request body

The structured intent

Response

​Building the sign-in

​Request body

​The structured intent

​Response

Building the sign-in

Request body

The structured intent

Response