API Reference · v1

Agent-First API Reference

Authentication

  • Header: X-PAYMENT: <base64 signed USDC>
  • No api key, no account, no onboarding — wallet is taken from the signed payment.
  • Used by POST /v1/chat/completions, /v1/auth/agent-onboard, and /v1/credits/purchase.

Errors

  • 400 — unsupported combo (e.g. stream:true on x402)
  • 401 — invalid or missing auth
  • 402 — payment required or credits exhausted
  • 403 — wallet mismatch
  • 409 — idempotency conflict
  • 422 — request body validation

Rate limits

  • Wallet-scoped, separate quotas for control-plane vs runtime.
  • Monitor credits and rotate keys/sessions for resilient clients.
  • x402 callers are rate-limited by wallet, not by api key.
Inference

The one endpoint most agents need. Per-token billing — pay-per-call with x402, or use an API key that debits credits from a pre-funded balance.

POST/v1/chat/completions

Chat completions — billed per token.

OpenAI-style LLM completions with optional wallet-scoped vector memory. Pay per call via X-PAYMENT (x402 USDC) or x-api-key (debits credits).

Auth x402 OR API keyBilled Per-token
Parameters
messagesarrayrequired

Chat messages.

modelenum

Gemini model: gemini-2.5-flash (default), gemini-2.5-flash-lite (cheapest), gemini-2.5-pro (most capable), gemini-3.1-flash-lite (newer Lite, better reasoning), or gemini-3.5-flash (newest Pro-tier reasoner). Per-token rate varies by model — see the rate sheet on the home page.

memory_readboolean

Retrieve memory context. Default true.

memory_writeboolean

Store user/assistant memory. Default true.

memory_write_modeenum

auto|raw|summary for memory writes. Default auto.

memory_max_charsinteger

Max chars stored per memory write artifact. Default 1200.

kinteger

Top-k memories.

temperaturenumber

Generation temperature.

streamboolean

Emit OpenAI-compatible SSE chunks instead of a single JSON response. Default false. Only valid on the api-key path; x402 requests with stream:true return 400.

request.sh
curl -X POST https://api.vectorway.io/v1/chat/completions \
  -H "X-PAYMENT: <base64 signed USDC payment>" \
  -H "Content-Type: application/json" \
  -d '{
  "messages":[{"role":"user","content":"Summarize our last run"}],
  "model":"gemini-2.5-flash",
  "memory_read":true,
  "memory_write":true,
  "memory_write_mode":"auto",
  "memory_max_chars":1200,
  "k":5,
  "temperature":0.3,
  "stream":false
}'
Auth (SIWE + JWT, agent-first)

Wallet authentication and JWT session lifecycle for agent-first accounts.

POST/v1/auth/agent-onboard

Onboard agent with x402 payment.

Verifies x402 payment, creates account if needed, grants credits, issues a JWT, and returns a new API key.

Auth x402 headersBilled x402 settled
Parameters
wallet_addressstringrequired

Wallet to onboard and credit.

creditsintegerrequired

Credits to add. Min 500,000 (≈$0.50 floor), max 1,000,000,000 (≈$1000 ceiling). 1 credit = 1 atomic USDC = $0.000001 → linear $1 → 1,000,000 credits.

key_namestring

Optional API key display name.

request.sh
curl -X POST https://api.vectorway.io/v1/auth/agent-onboard \
  -H "X-PAYMENT: <base64 signed USDC payment>" \
  -H "Content-Type: application/json" \
  -d '{
  "wallet_address":"0xabc...",
  "credits":5000000,
  "key_name":"agent-prod"
}'
POST/v1/auth/siwe/challenge

Generate SIWE challenge message.

Creates nonce-backed SIWE message for a wallet.

Auth noneBilled free
Parameters
wallet_addressstringrequired

Wallet address for challenge issuance.

chain_idinteger

EVM chain ID. Default 1.

request.sh
curl -X POST https://api.vectorway.io/v1/auth/siwe/challenge \
  -H "Content-Type: application/json" \
  -d '{
  "wallet_address": "0xabc...",
  "chain_id": 1
}'
POST/v1/auth/siwe/verify

Verify SIWE and issue JWT session.

Verifies signature + nonce, creates/loads an agent-first account, and returns access + refresh JWTs.

Auth SIWE signature payloadBilled free
Parameters
wallet_addressstringrequired

Wallet being authenticated.

messagestringrequired

SIWE message returned by challenge.

signaturestringrequired

Wallet signature over SIWE message.

request.sh
curl -X POST https://api.vectorway.io/v1/auth/siwe/verify \
  -H "Content-Type: application/json" \
  -d '{
  "wallet_address": "0xabc...",
  "message": "localhost wants you to sign in...",
  "signature": "0x..."
}'
POST/v1/auth/refresh

Rotate refresh token.

Consumes current refresh token and returns a new access+refresh pair.

Auth noneBilled free
Parameters
refresh_tokenstringrequired

Current refresh JWT.

request.sh
curl -X POST https://api.vectorway.io/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"eyJ..."}'
POST/v1/auth/revoke

Revoke refresh token.

Invalidates provided refresh token (logout).

Auth noneBilled free
Parameters
refresh_tokenstringrequired

Refresh JWT to revoke.

request.sh
curl -X POST https://api.vectorway.io/v1/auth/revoke \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"eyJ..."}'
Accounts

Wallet account state, compatibility aliases, and API call history.

GET/v1/me

Get current account state.

JWT-gated account profile for the authenticated wallet.

Auth JWT bearerBilled free
Parameters
No parameters.
request.sh
curl https://api.vectorway.io/v1/me \
  -H "Authorization: Bearer <ACCESS_JWT>"
GET/v1/usage

List API call history.

Wallet-scoped call history (newest first).

Auth JWT or API keyBilled free
Parameters
limitinteger

Events per page. 1–100, default 50.

cursorinteger

Opaque list offset from a previous response's next_cursor. Omit for the first page.

filterstring

Either "all" (default), "errors" (status ≥ 400), or an exact request path (e.g. "/v1/chat/completions") for path-scoped reads.

request.sh
curl https://api.vectorway.io/v1/usage?limit=50&cursor=0&filter=all \
  -H "Authorization: Bearer <ACCESS_JWT>"
Credits & Billing

Top-ups, Stripe checkout, balance, and the credit-movement ledger.

POST/v1/credits/purchase

Top up credit balance via x402.

x402 payment proof endpoint. Wallet must already have an account and match the wallet in the payment proof.

Auth x402 headersBilled x402 settled
Parameters
wallet_addressstringrequired

Wallet to credit.

creditsintegerrequired

Credits to add (1 credit = 1 atomic USDC = $0.000001). Min 500,000 (≈$0.50), max 1,000,000,000 (≈$1000).

request.sh
curl -X POST https://api.vectorway.io/v1/credits/purchase \
  -H "X-PAYMENT: <base64 signed USDC payment>" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xabc...","credits":5000000}'
GET/v1/credits/me

Get credit balance for current account.

Works with JWT bearer (control plane) or API key (runtime). `credits` is the wallet's current credit balance (1 credit = $0.000001).

Auth JWT bearerBilled free
Parameters
No parameters.
request.sh
curl https://api.vectorway.io/v1/credits/me \
  -H "Authorization: Bearer <ACCESS_JWT>"
GET/v1/credits/ledger

List credit-movement history.

Wallet-scoped credit ledger (newest first) covering top-ups, refunds, and grants.

Auth JWT or API keyBilled free
Parameters
limitinteger

Events per page. 1–100, default 50.

cursorinteger

Opaque list offset from a previous response's next_cursor.

kindstring

Optional filter: "topup" | "debit" | "refund" | "grant". Omit to return every kind. Case-insensitive.

request.sh
curl https://api.vectorway.io/v1/credits/ledger?limit=50&cursor=0&kind=topup \
  -H "Authorization: Bearer <ACCESS_JWT>"
API Key Management

API key creation, listing, and revocation.

POST/v1/api-keys

Create API key.

JWT control-plane endpoint. Returns raw key once.

Auth JWT bearerBilled free
Parameters
wallet_addressstringrequired

Wallet owner of key.

key_namestringrequired

Display name for key.

request.sh
curl -X POST https://api.vectorway.io/v1/api-keys \
  -H "Authorization: Bearer <ACCESS_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xabc...","key_name":"my-agent"}'
GET/v1/api-keys

List API keys.

Returns API key metadata for wallet.

Auth JWT bearerBilled free
Parameters
No parameters.
request.sh
curl https://api.vectorway.io/v1/api-keys \
  -H "Authorization: Bearer <ACCESS_JWT>"
DELETE/v1/api-keys/{key_id}

Revoke API key.

Deletes selected key if it belongs to wallet.

Auth JWT bearerBilled free
Parameters
key_idpath stringrequired

API key identifier.

wallet_addressstringrequired

Wallet owner.

request.sh
curl -X DELETE https://api.vectorway.io/v1/api-keys/{key_id} \
  -H "Authorization: Bearer <ACCESS_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xabc..."}'
Memory

Read-only introspection over the wallet-scoped vector index. Memory is populated by the chat endpoint when memory_write=true.

DELETE/v1/memory/{memory_id}

Delete a memory item.

Deletes a wallet-scoped memory record by id. Use the id returned by a memory-search match.

Auth API keyBilled free
Parameters
memory_idpath stringrequired

Memory identifier returned by GET /v1/memory.

request.sh
curl -X DELETE https://api.vectorway.io/v1/memory/{memory_id} \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '# no body'

Need something not listed? Open an issue or sign a message at support@vectorway.io.