The async agent API
An API-key endpoint that runs a full agent turn and returns the collected result — the same pipeline the terminal streams live.
Lifecycle
- POST /agent/job
- Start a job. Body: prompt, threadId?, history?, model? → {jobId}
- GET /agent/job/:id
- Poll status → {status, response, richData, cancellable}
- POST /agent/job/:id/cancel
- Cancel — only while status is pending
Statuses: pending → processing → completed | failed | cancelled. Poll every couple of seconds — the CLI polls at 1.5s. Jobs are scoped to the key's wallet: asking for someone else's job is a 403, not a 404.
curl -X POST https://api.vectr.bot/agent/job \
-H "X-API-Key: vectr_…" -H "Content-Type: application/json" \
-d '{"prompt":"what did my last three launches earn"}'
curl https://api.vectr.bot/agent/job/<jobId> -H "X-API-Key: vectr_…"What comes back
| Field | Contents |
|---|---|
| response | The agent's full text answer — every streamed chunk joined |
| richData | Set when the turn produced a transaction: the unsigned to/data/value the wallet owner confirms in the terminal |
| error | Set on failed — a client-safe message, never a stack trace |
- response
- Contents
- The agent's full text answer — every streamed chunk joined
- richData
- Contents
- Set when the turn produced a transaction: the unsigned to/data/value the wallet owner confirms in the terminal
- error
- Contents
- Set on failed — a client-safe message, never a stack trace
richData is a request, not a receipt
A job that returns a transaction has not executed anything — it built an unsigned payload. The wallet owner reviews and confirms it in the terminal; the job API itself never signs.
Streaming instead: POST /agent/prompt
The session-authenticated variant streams the same turn over SSE (events like usage_update, text deltas, transaction, done) — it's what the terminal UI uses. Cookie auth, not API key, so it is a browser surface rather than a scripting one.
Agent memory
- GET /agent/memory
- Everything the agent has stored for this wallet
- DELETE /agent/memory/:key
- Delete one memory
Memory is how the agent remembers preferences across turns — "always use 2% slippage". Both endpoints are session-only; they manage the user's own data, not a bot surface.