# Vectorway

> Vectorway is the agentic memory LLM gateway: OpenAI-compatible chat completions over Gemini 2.5 Flash/Pro with built-in wallet-scoped vector memory. `POST /v1/chat/completions` is dual-auth — call it pay-per-call with an x402 `X-PAYMENT` header (no onboarding, no account, no api key) OR with an `x-api-key` against a SIWE-onboarded credit balance. Built so AI agents can self-onboard, pay, and infer with no human in the loop.

Use these resources when integrating with Vectorway from another LLM or agent runtime.

## Primary docs
- [Agent Skill (drop-in SKILL.md)](https://vectorway.io/skill.md): prescriptive 1-page playbook with YAML frontmatter — install into `~/.cursor/skills/vectorway/SKILL.md` (or any Anthropic Agent Skills folder) to auto-invoke this integration on relevant prompts.
- [API reference (markdown)](https://vectorway.io/llms-full.txt): every public endpoint, full request/response examples, and curl recipes.
- [API reference (markdown alias)](https://vectorway.io/docs.md): same content as `llms-full.txt`, served as `text/markdown`.
- [OpenAPI 3.1 spec](https://vectorway.io/openapi.json): machine-readable schema for codegen, MCP servers, or tool registration.
- [Human docs site](https://vectorway.io/docs): rendered HTML version of the API reference.

## Endpoints
### 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.

### 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.
- `POST /v1/auth/siwe/challenge` — Generate SIWE challenge message.
- `POST /v1/auth/siwe/verify` — Verify SIWE and issue JWT session.
- `POST /v1/auth/refresh` — Rotate refresh token.
- `POST /v1/auth/revoke` — Revoke refresh token.

### Accounts
Wallet account state, compatibility aliases, and API call history.
- `GET /v1/me` — Get current account state.
- `GET /v1/usage` — List API call history.

### Credits & Billing
Top-ups, Stripe checkout, balance, and the credit-movement ledger.
- `POST /v1/credits/purchase` — Top up credit balance via x402.
- `GET /v1/credits/me` — Get credit balance for current account.
- `GET /v1/credits/ledger` — List credit-movement history.

### API Key Management
API key creation, listing, and revocation.
- `POST /v1/api-keys` — Create API key.
- `GET /v1/api-keys` — List API keys.
- `DELETE /v1/api-keys/{key_id}` — Revoke API key.

### Memory
Read-only introspection over the wallet-scoped vector index. Memory is populated by the chat endpoint when memory_write=true.
- `GET /v1/memory` — Search memories.
- `DELETE /v1/memory/{memory_id}` — Delete a memory item.

## Conventions
- Base URL: `https://api.vectorway.io`
- **`POST /v1/chat/completions` is dual-auth**: send a per-call x402 `X-PAYMENT` to pay USDC per request with no onboarding and no api key, OR send `x-api-key` to debit credits against a pre-funded balance. Both paths price the same per-token math; only the unit of payment differs. Both paths return identical JSON.
- Auth modes (x402-first): `X-PAYMENT` for pay-per-call USDC and any settlement endpoint; `x-api-key` for runtime against a credit balance; `Authorization: Bearer <jwt>` for SIWE-issued control-plane sessions. Read-only history endpoints (`/v1/usage`, `/v1/credits/ledger`) accept JWT *or* api-key — pure-x402 callers SIWE once to audit their own wallet.
- Error model: standard HTTP status codes. `400` for unsupported combinations (e.g. `stream:true` on x402), `401` invalid/missing auth, `402` payment required or credits exhausted, `403` wallet mismatch, `409` idempotency conflict, `422` body validation, `429` rate limits.
- Credits accounting: 1 credit = 1 atomic USDC = $0.000001. Chat is billed per token; the x402 path floors settlement at $0.001 to handle the facilitator minimum, the api-key path has no floor. Per-call USDC settlements on the x402 path are surfaced on `/v1/usage` as `usd_cost` (the same number as `cost / 1_000_000` for reconciling against on-chain transfers).

## Optional
- [Status](https://vectorway.io/status): live gateway, vector store, and payment verifier health.
- [Sitemap](https://vectorway.io/sitemap.xml)