Voidnet

The Voidnet is the central routing layer of the Voidnet Console platform. You send it a request; it authenticates you, enforces your subscription and usage limits, and proxies the request to the publisher's server. You never connect to a publisher directly.

Buyer (API key or JWT)  →  Voidnet  →  Publisher's server

What the gateway does

1. Authenticates your credential (API key or JWT).
2. Checks your purchase of the app and your tier's meter.
3. Enforces rate limits (per-minute, per-day, monthly meter).
4. Routes the request to the publisher's server.
5. Returns the publisher's response, or a gateway error if something fails.

You do not need to know the publisher's server URL. The gateway resolves it from the username/appname in your request path.

Endpoint

All app requests go through one endpoint. The adapter in the path selects the protocol:

POST /v1-beta/{adapter}/{username}/{appname}

MCP — Stateless 2026-07-28:

• Only POST is supported. GET and DELETE return 405 Method Not Allowed.
• SSE streams are per-request on POST; close = cancel. No Last-Event-ID, no Mcp-Session-Id.

LLM — OpenAI compatible:

POST /v1-beta/llm/{username}/{appname}
Authorization: Bearer vnb-sk-...
Content-Type: application/json

Body: {"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"hi"}],"stream":false}

• One model per app — the model you send must match the app's published model exactly.
• stream:true is supported (SSE); the gateway injects stream_options.include_usage:true when missing, and streams without a final usage chunk fail loudly instead of going unbilled. Multimodal inputs (image_url, audio) are rejected — TEXT only.
• Your LLM server must expose POST {serverUrl}/v1/chat/completions and accept any Authorization: Bearer <token> header.

Plus operational endpoints:

For the full request/response schema of every operation, see the API Reference — it is generated from the gateway source and cannot drift.

Authentication

Two credential types, both in the Authorization: Bearer header. The gateway auto-detects which you're using:

• API keys (vnb-sk-*, vai-sk-*) — long-lived, generated in the Console.
• JWT access tokens — short-lived (1 hour), obtained from POST /oauth/token. Use these in production.

A 3-segment (dot-separated) value is treated as a JWT; a vnb-sk-/vai-sk- prefix is treated as an API key.

Errors

All gateway errors use one shape (OAuth endpoints are the exception — see Error Reference):

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "status": 429
  }
}