{"instructions":"# Koinelix API\n\n\u003e Pay-per-call APIs for agents: image generation and editing, image recognition and file upload. Pay in USDC on Base with x402; no account, no API key.\n\n## Services\n\n- Image generation: POST https://api.koinelix.com/v1/images/generations, 0.021 USDC. Use when an agent needs a picture from a text prompt, optionally edited from reference images; the image returns as Base64 JSON.\n- Image recognition: POST https://api.koinelix.com/v1/images/recognitions, 0.011 USDC. Use when an agent needs to describe a picture, answer a question about it or read its text; send an image URL or Base64.\n- File upload: POST https://api.koinelix.com/v1/files, 0.004 USDC. Use when an agent holds a file (up to 10 MiB) and needs to hand it on as a URL; send multipart/form-data with one part named file, or JSON with the file as base64 (up to 8 MiB). A signed download link valid for 10 days returns.\n\n## How to call\n\n1. Send the request to the endpoint without a payment to receive HTTP 402 with a PAYMENT-REQUIRED x402 v2 quote.\n2. Sign the exact quote with an x402 client and resend the same request with the PAYMENT-SIGNATURE header.\n3. If the response is lost, resend the same request with the same PAYMENT-SIGNATURE instead of paying again.\n\n## Examples with curl\n\ncurl cannot sign an x402 payment: PAYMENT_SIGNATURE is the quote signed by your wallet or x402 client.\n\n### Image generation\n\n```bash\n# 1. Get the quote: no payment. Returns HTTP 402 with the PAYMENT-REQUIRED header.\ncurl -i -X POST https://api.koinelix.com/v1/images/generations \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"prompt\":\"A watercolor lighthouse at sunrise\"}'\n\n# 2. Generate with the signed payment (PAYMENT_SIGNATURE is the quote signed by your wallet or x402 client).\ncurl --max-time 120 -X POST https://api.koinelix.com/v1/images/generations \\\n  -H \"PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"prompt\":\"A watercolor lighthouse at sunrise\"}' -o response.json\n\n# 3. Save the image: the result is Base64 in data[0].b64_json.\njq -r '.data[0].b64_json' response.json | base64 --decode \u003e image.png\n```\n\n### Image recognition\n\n```bash\n# 1. Get the quote: no payment. Returns HTTP 402 with the PAYMENT-REQUIRED header.\ncurl -i -X POST https://api.koinelix.com/v1/images/recognitions \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"image_url\":\"https://example.com/photo.jpg\"}'\n\n# 2. Recognize with the signed payment (PAYMENT_SIGNATURE is the quote signed by your wallet or x402 client).\ncurl --max-time 120 -X POST https://api.koinelix.com/v1/images/recognitions \\\n  -H \"PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"image_url\":\"https://example.com/photo.jpg\",\"prompt\":\"What is in this image?\"}'\n# The answer is in the content field of the JSON response.\n```\n\n### File upload\n\n```bash\n# 1. Get the quote: no payment, no body. Returns HTTP 402 with the PAYMENT-REQUIRED header.\ncurl -i -X POST https://api.koinelix.com/v1/files\n\n# 2. Upload with the signed payment (PAYMENT_SIGNATURE is the quote signed by your wallet or x402 client).\ncurl -X POST https://api.koinelix.com/v1/files \\\n  -H \"PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE\" \\\n  -F \"file=@photo.png\"\n```\n\nMore examples (Base64 input, JSON upload): https://api.koinelix.com/agents.md.\n\n## Documents\n\n- Agent guide with examples: https://api.koinelix.com/agents.md\n- OpenAPI: https://api.koinelix.com/openapi.json\n- x402 discovery: https://api.koinelix.com/.well-known/x402\n\n## Language models — actual token settlement\n\nUse LLM for conversation, writing, code and local function definitions. Receive streaming or non-streaming responses. Discover available models, supported_protocols endpoints, pricing, context_window and max_output_tokens with GET https://api.koinelix.com/v1/models. Keep the input within the model's context_window and the output budget within its max_output_tokens; larger requests are rejected before payment.\n\nPayment: x402 v2 upto / Permit2; network eip155:8453; asset 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913. Prices are USD per million tokens, settled at the same numeric USDC amount. Minimum charge: 0.002000 USDC per call. Final billing uses actual input, cached input, cache writes and output at the applicable quoted rates.\n\n1. Select a model id and an endpoint from its supported_protocols. Set a maximum output budget. For Chat Completions send messages and max_completion_tokens; for Responses send input and max_output_tokens. Set stream=true for SSE.\n2. POST the request as application/json with a unique Idempotency-Key. HTTP 402 and PAYMENT-REQUIRED contain the request-specific quote. Decode the base64 JSON and select scheme=upto. Verify x402Version, network, asset, trusted payTo, amount, expiry, resource URL and your spending policy.\n3. Use an x402 v2 upto / Permit2 client to prepare a bounded token allowance within your spending policy and sign the quoted authorization. Token allowance and this call's signed limit are separate. Signing authorizes a maximum; funds transfer at settlement after generation.\n4. Resend the identical body and path with PAYMENT-SIGNATURE, the same Idempotency-Key and the same authentication identity. Changing input, model, protocol or output budget requires a new quote and signature. The gateway binds payment to the original request.\n5. Save the response on the client. The final bill is calculated after final usage, subject to the signed limit and minimum charge. Non-streaming completes settlement before returning the full response. Streaming emits text first and settles after final usage.\n6. For SSE or a lost/interrupted response, POST the original endpoint/body with the original PAYMENT-SIGNATURE, Idempotency-Key and identity plus X-Koinelix-Recover-Only: true. Record X-Request-ID (HTTP trace) and X-Koinelix-Request-Id (invocation ID) separately. Read request_id, execution, usage, payment, delivery, amount, tx_hash and result_stored. amount is a nullable integer string in atomic USDC units (6 decimals). result_stored=false means response text is retained by the caller only. payment=settled means the gateway verified settlement. Use bounded backoff while processing, for example 2, 4, 8, 16 and 30 seconds, stopping after five attempts and retaining the pending state. Keep unknown outcomes on the original authorization; do not create another payment to resolve an unknown one. Recovery reports state, not retained response text.\n7. For 429 respect Retry-After. A 429 without X-Koinelix-Request-Id was rejected before admission: retain the same intent and retry, except daily_cap_exceeded, which does not succeed again until the next day. A 429 capacity_exhausted with X-Koinelix-Request-Id was rejected after admission: recover it (expect execution=failed, payment=not_required), then request a new quote for a new intent; the original authorization cannot be reused. For configuration_changed or intent_mismatch, recover any existing call first, then request a new quote for a new unexecuted intent. For quote_estimation_unsupported adjust the request to a supported shape; for quote_estimation_unavailable retry with bounded backoff. Inspect the returned error code and request ID.\n8. An expired unexecuted quote may be replaced after checking the original call. intent_mismatch requires restoring the original request for recovery or getting a new quote for a new intent. Missing usage, over-budget usage and unknown settlement are distinct errors: retain the request identifier for investigation.\n\nReference client: https://koinelix.com/examples/llm-upto-client.mjs (v1.0.0, no external dependencies, EIP-1193 wallet adapter). Use prepareLLM with a trusted network/asset/payee/account/maxAtomic policy; approve only under your allowance policy, wait for its receipt, execute once, consume the JSON or SSE body, then recover the original session. Keep that session in protected memory.\n\nExample quote request (replace \u003cmodel-id\u003e with a catalog id):\n\nPOST https://api.koinelix.com/v1/chat/completions\nContent-Type: application/json\nIdempotency-Key: \u003cunique-request-id\u003e\n\n{\"model\":\"\u003cmodel-id\u003e\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain your capabilities in two sentences.\"}],\"max_completion_tokens\":256,\"stream\":false}\n\nResponses alternative:\nPOST https://api.koinelix.com/v1/responses\n{\"model\":\"\u003cmodel-id\u003e\",\"input\":\"Explain your capabilities in two sentences.\",\"max_output_tokens\":256,\"stream\":true}\n\n","resources":["https://api.koinelix.com/v1/images/generations","https://api.koinelix.com/v1/images/recognitions","https://api.koinelix.com/v1/files","https://api.koinelix.com/v1/chat/completions","https://api.koinelix.com/v1/responses"],"version":1}