API Reference · v1

Agent-First API Reference

Vectorway APIs can be used entirely by agents with no human intervention by using SIWE. Use SIWE to obtain JWT sessions for control-plane operations, then use API keys for runtime endpoints such as chat inference.

Authentication

Control-plane endpoints use Authorization: Bearer <access_jwt>. Runtime inference uses x-api-key. x402 topups require x-payment-signature and x-payment-tx-hash.

Errors

RFC 7807 problem+json. Common: 401 auth invalid, 402 insufficient credits/payment required, 403 wallet mismatch, 409 idempotency conflict, 422 validation.

Rate limits

Rate limits are wallet-scoped and may differ across control-plane and runtime endpoints. Use credits monitoring plus key/session rotation for resilient clients.

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, adds credits, issues JWT, and returns a new API key.

Auth x402 headersBilled x402 settled

Parameters

wallet_addressstringrequired

Wallet to onboard and credit.

creditsintegerrequired

Credits to add after x402 verification.

key_namestring

Optional API key display name.

request.sh

curl -X POST https://api.vectorway.ai/v1/auth/agent-onboard \
  -H "x-payment-signature: <SIGNATURE>" \
  -H "x-payment-tx-hash: <TX_HASH>" \
  -H "Content-Type: application/json" \
  -d '{
  "wallet_address":"0xabc...",
  "credits":5000,
  "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.ai/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.ai/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.ai/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.ai/v1/auth/revoke \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"eyJ..."}'

Accounts

Wallet account state and compatibility aliases.

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.ai/v1/me \
  -H "Authorization: Bearer <ACCESS_JWT>"

Credits & Billing

Topups, checkout flows, and balance reads.

POST/v1/credits/purchase

Purchase credits 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.

request.sh

curl -X POST https://api.vectorway.ai/v1/credits/purchase \
  -H "x-payment-signature: <SIGNATURE>" \
  -H "x-payment-tx-hash: <TX_HASH>" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xabc...","credits":500}'

GET/v1/credits/me

Get credits for current principal.

Works with JWT bearer (control plane) or API key (runtime).

Auth JWT bearerBilled free

Parameters

No parameters.

request.sh

curl https://api.vectorway.ai/v1/credits/me \
  -H "Authorization: Bearer <ACCESS_JWT>"

API Key Management

Control-plane 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.ai/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.ai/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.ai/v1/api-keys/{key_id} \
  -H "Authorization: Bearer <ACCESS_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xabc..."}'

Inference Runtime

Agent runtime endpoints (API-key authenticated).

POST/v1/chat/completions

Inference endpoint.

Runtime data-plane endpoint. memory_read/memory_write control memory behavior; enabling either increases credits charged.

Auth API keyBilled higher if memory_read OR memory_write

Parameters

messagesarrayrequired

Chat messages.

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.

request.sh

curl -X POST https://api.vectorway.ai/v1/chat/completions \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "messages":[{"role":"user","content":"Summarize our last run"}],
  "memory_read":true,
  "memory_write":true,
  "memory_write_mode":"auto",
  "memory_max_chars":1200,
  "k":5,
  "temperature":0.3
}'

POST/v1/memory

Generate embedding and store memory.

Generates an embedding for content and stores both text + vector in wallet-scoped memory.

Auth API keyBilled runtime credits

Parameters

contentstringrequired

Memory text to store.

request.sh

curl -X POST https://api.vectorway.ai/v1/memory \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"content":"Customer prefers async delivery on Tuesdays."}'

GET/v1/memory

Search memories.

Semantic search over wallet-scoped memory index.

Auth API keyBilled runtime credits

Parameters

qstringrequired

Semantic query text.

kinteger

Result count. Default 5.

request.sh

curl https://api.vectorway.ai/v1/memory?q=last+simulation&k=5 \
  -H "x-api-key: <API_KEY>"

DELETE/v1/memory/{memory_id}

Delete a memory item.

Deletes a wallet-scoped memory record by id.

Auth API keyBilled runtime credits

Parameters

memory_idpath stringrequired

Memory identifier returned by POST /v1/memory.

request.sh

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

POST/v1/embeddings

Generate embeddings.

Returns embedding vectors for one or many inputs.

Auth API keyBilled runtime credits

Parameters

inputstring|string[]required

Input text(s).

request.sh

curl -X POST https://api.vectorway.ai/v1/embeddings \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"input":["hello","world"]}'