DOCUMENTATION
Koinelix platform
Pay-per-call APIs for AI agents. Every service shares one payment flow, so an agent that can pay for one can call them all.
Overview
Koinelix publishes APIs that agents and developers call over HTTP. Each call is paid in USDC on Base with the x402 protocol: no signup and no API key.
Every service is described in machine-readable documents, so an agent can find the endpoint, price and payment details on its own. Account holders can use a platform API key with quota granted by Koinelix instead.
Services
Services on the platform. More are added over time and appear here and in the discovery documents.
| Service | What it does | Status |
|---|---|---|
| Image generation | Turn a text prompt into an image with one HTTP request. | — |
More services are on the way.
Calling a service
All paid endpoints follow the same flow.
- Send the request with no payment. The API replies 402 and the PAYMENT-REQUIRED header carries a Base64 x402 v2 quote.
- Check X-Koinelix-Availability. If it says unavailable, do not sign: payments are paused and a signed request returns 503 without being charged.
- Sign the exact quote with your wallet and send the same request again with the PAYMENT-SIGNATURE header.
- The payment settles, the service runs, and the 200 response carries PAYMENT-RESPONSE with the settlement result.
Headers
| Header | Direction | Description |
|---|---|---|
PAYMENT-REQUIRED | Response | Base64 x402 v2 quote on 402 responses: price, network, asset, payee. |
PAYMENT-SIGNATURE | Request | Base64 payment authorization that answers the quote. |
PAYMENT-RESPONSE | Response | Base64 settlement result on successful paid calls. |
X-Koinelix-Availability | Response | ready or unavailable, sent with 402 quotes. |
Authorization | Request | Bearer platform API key. Omit it for anonymous x402. |
Idempotency-Key | Request | Required with an API key; optional and only format-checked for anonymous calls. |
Retry-After | Response | Seconds to wait after a 429. |
Authentication
Anonymous x402
Send no Authorization header. An unsigned request returns 402 with the quote before the body is read. A signed request is validated first, then verified and settled. Each new payment authorization buys one attempt, with no refund and no retry.
Platform API key
Send Authorization: Bearer <key> and a unique Idempotency-Key. Quota is used first; if there is none, the API returns a 402 quote. One payment allows up to three attempts. A key that is present but invalid returns 401 and is never treated as anonymous.
Recovering a lost response
If the connection drops after you signed, do not pay again. Resend the same request body with the same PAYMENT-SIGNATURE header. The API returns the original status without charging a second time.
Whether a finished result can still be returned depends on the service; each service page says so.
Errors
Errors use the shape { "error": { "code", "message" } }. Branch on the code, not on the message. These codes apply to every paid service; service pages list their own. Treat a code you do not recognize by its HTTP status.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | validation_failed | The request is not valid. The message names the problem; a signed payment is not verified or settled. |
| 400 | price_not_configured | No price is configured yet, so no quote can be made. |
| 401 | invalid_api_key | An Authorization header is present but the key is missing or invalid. |
| 402 | payment_required | No payment yet. The PAYMENT-REQUIRED header holds the quote. |
| 402 | payment_invalid | The PAYMENT-SIGNATURE header is not valid. |
| 402 | payment_quote_mismatch | The price changed since you signed. Request a new quote. |
| 402 | settlement_failed | The payment was not settled and you were not charged. Request a new quote and try again. |
| 405 | method_not_allowed | Use POST. GET and HEAD are quote probes and take no payment. |
| 409 | payment_authorization_conflict | This payment authorization already belongs to another request. |
| 409 | payment_reuse_conflict | The authorization cannot be reused for a different request. |
| 409 | attempt_in_progress | An attempt for this payment is still running. Wait and retry the same request. |
| 415 | unsupported_media_type | Send Content-Type: application/json. |
| 429 | rate_limited | Too many requests. Wait for the Retry-After seconds. |
| 503 | payment_unavailable | Payment verification or settlement is temporarily unavailable. Nothing was charged. |
| 503 | service_paused | The service is paused or not open yet. Nothing was charged. |
Discovery documents
Machine-readable descriptions are served from the API host once a service is open.
- OpenAPI 3.1 with payment info
https://api.koinelix.com/openapi.json - x402 resource list
https://api.koinelix.com/.well-known/x402 - Agent guide in Markdown
https://api.koinelix.com/agents.md