# Singular Complete Documentation

> Complete Markdown bundle for broad ingestion. Prefer /llms.txt and individual pages for ordinary tasks.

Updated: 2026-08-10
Canonical docs: https://singular.impossibuild.ai/docs
Canonical API origin: https://api.impossi.build
OpenAI SDK base URL: https://api.impossi.build/v1

## Contract summary

- Stable: OpenAI-shaped Chat Completions and Chat streaming.
- Limited: opaque authenticated model list, native Anthropic Messages only with a true Anthropic-wire target, best-effort tools/structured output, and BYOK controls that do not bypass Singular credit billing.
- Not a public product-key surface: OpenAI Responses, native Gemini, files, batches, fine-tuning, realtime, and legacy completions.
- Deployment gated: x402 and Singular-specific MPP charge methods; the live 402 challenge is authoritative.

## Source-of-truth order

1. Live API response and headers.
2. Live pricing JSON for catalog data.
3. Individual documentation pages in this bundle.
4. Upstream provider documentation for model-specific behavior.

---

## Home

Start from the live Singular contract and choose the documentation section that matches your task.

### Developer documentation

Source: https://singular.impossibuild.ai/docs
Section: Home
Documentation kind: home
Maturity: Stable
Keywords: Singular, model routing, OpenAI compatibility, API, x402, MPP
Related: [Tutorials](https://singular.impossibuild.ai/docs/tutorials), [How-to guides](https://singular.impossibuild.ai/docs/how-to-guides), [Reference](https://singular.impossibuild.ai/docs/reference), [Explanation](https://singular.impossibuild.ai/docs/explanation)

One API key, a live multi-provider model catalog, OpenAI-shaped chat, and optional machine-payment rails.

#### Start with the contract that is live

Singular exposes its API at `https://api.impossi.build/v1`. The stable compatibility surface is **OpenAI Chat Completions**. Claude, Gemini, Kimi, DeepSeek, and other catalog models are called through that same OpenAI-shaped endpoint by changing the model ID.

> Compatibility is endpoint-specific. A registered route does not automatically mean full OpenAI or Anthropic parity. The compatibility matrix in these docs is based on the current request normalizer, router, handlers, and public deployment, not route names alone.

| Surface | Status | Source of truth |
| --- | --- | --- |
| OpenAI Chat Completions | Stable | `POST https://api.impossi.build/v1/chat/completions` |
| Public model and price catalog | Stable | [Model catalog](https://singular.impossibuild.ai/models) and [pricing JSON](https://api.impossi.build/pricing.json) |
| Streaming Chat Completions | Stable | OpenAI-style data-only SSE ending in `data: [DONE]` |
| Anthropic Messages | Limited | Provider-native route only; not a universal translation layer for the current NanoGPT/AIsa-backed pool |
| OpenAI Responses | Not a public product-key surface | Use Chat Completions |
| x402 and MPP | Deployment gated | The live `402` challenge is authoritative for enabled rails and networks |

#### Canonical URLs

- Web app: [https://singular.impossibuild.ai](https://singular.impossibuild.ai)
- Human documentation: [https://singular.impossibuild.ai/docs](https://singular.impossibuild.ai/docs)
- API origin: [https://api.impossi.build](https://api.impossi.build)
- OpenAI SDK base URL: `https://api.impossi.build/v1`
- Live retail pricing: [https://api.impossi.build/pricing.json](https://api.impossi.build/pricing.json)
- LLM-readable index: [https://singular.impossibuild.ai/llms.txt](https://singular.impossibuild.ai/llms.txt)
- Full LLM-readable reference: [https://singular.impossibuild.ai/llms-full.txt](https://singular.impossibuild.ai/llms-full.txt)

#### Choose the right documentation section

Choose the section that matches what you need now: learn by completing a working result, solve a specific task, find an exact contract, or understand why the system behaves as it does.

| Section | Use it when | Start with |
| --- | --- | --- |
| Tutorials | You are learning Singular through a guided lesson. | [Tutorials](https://singular.impossibuild.ai/docs/tutorials) |
| How-to guides | You know the outcome you need and want a practical procedure. | [How-to guides](https://singular.impossibuild.ai/docs/how-to-guides) |
| Reference | You need the exact contract, field support, status, or limitation. | [Reference](https://singular.impossibuild.ai/docs/reference) |
| Explanation | You want to understand why the system behaves as it does. | [Explanation](https://singular.impossibuild.ai/docs/explanation) |

#### What Singular adds

- A live catalog spanning multiple upstream providers behind one request shape.
- Explicit model selection or `model: "auto"` for policy-based routing.
- Provider health, fallback, prepaid billing, usage metering, API keys, and BYOK controls.
- A web workspace with threads, branching, comparisons, citations, spaces, sharing, and exports.
- Optional accountless per-call payment handshakes using x402 v2 or Singular-specific MPP charge methods when enabled by the deployment.

#### Source-of-truth order

1. The response returned by the live API.
2. The live pricing catalog for model IDs, context, and positive retail rates.
3. This documentation for supported request shapes and known deviations.
4. Upstream provider documentation for model-specific behavior.

Do not infer that every model supports every parameter. Route and model capability are separate questions.

---

## Tutorials

Learn Singular by completing a working request from key claim through streaming.

### Learn Singular by building

Source: https://singular.impossibuild.ai/docs/tutorials
Section: Tutorials
Documentation kind: tutorial
Maturity: Informational
Keywords: tutorial, first request, curl, streaming
Related: [Quickstart](https://singular.impossibuild.ai/docs/quickstart), [How-to guides](https://singular.impossibuild.ai/docs/how-to-guides), [Reference](https://singular.impossibuild.ai/docs/reference)

Follow a guided path from a funded key to a verified routed response and a working stream.

#### Learn through a complete result

Tutorials are for learning Singular by completing a small working project. Start here if you have not made a request yet or want to verify the full path before integrating an SDK or application.

The [first-request tutorial](https://singular.impossibuild.ai/docs/quickstart) takes about ten minutes. You will claim a funded key, send one OpenAI-shaped Chat Completions request, verify the response, pin a catalog model, and confirm streaming termination.

#### What you need

- A terminal with `curl`.
- An email address for the prepaid claim flow.
- Permission to store the resulting `mr_...` key as a server-side secret.

#### After the tutorial

Use the [how-to guides](https://singular.impossibuild.ai/docs/how-to-guides) for a specific integration task, the [reference](https://singular.impossibuild.ai/docs/reference) for exact request behavior, and the [explanation section](https://singular.impossibuild.ai/docs/explanation) when you need the reasoning behind routing and platform boundaries.

---

### Make your first request

Source: https://singular.impossibuild.ai/docs/quickstart
Section: Tutorials
Documentation kind: tutorial
Maturity: Stable
Keywords: quickstart, curl, API key, auto routing, streaming
Related: [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [How routing works](https://singular.impossibuild.ai/docs/models-routing), [Streaming & errors](https://singular.impossibuild.ai/docs/streaming-errors)

Claim a funded key, verify one routed response, pin a live model, and confirm streaming from a terminal.

#### Before you begin

**Estimated time:** 10 minutes.

You need a terminal with `curl`, an email address for the prepaid claim flow, and a safe server-side place to store one secret. By the end, you will have a funded Singular API key and evidence that non-streaming, explicit-model, and streaming requests work from your environment.

#### 1. Claim a funded API key

Open the gateway's [prepaid top-up flow](https://api.impossi.build/topup), enter your receipt email, choose an amount, and complete checkout. After payment confirms, the gateway redirects to `/claim` and reveals the funded `mr_...` API key once. Copy that exact key immediately and use it below.

> Do not create a separate key in Settings for this Quickstart. Settings-created keys begin with zero balance, and the current self-service billing flow does not fund an individually issued Settings key.

#### 2. Configure your terminal

```bash
export SINGULAR_API_KEY="mr_your_key_here"
export OPENAI_BASE_URL="https://api.impossi.build/v1"
```

Keep the key on your server. Never embed it in browser code, a mobile binary, a public repository, screenshots, or client-side logs.

#### 3. Send one routed request

```bash
curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $SINGULAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain model routing in one sentence."}]
  }'
```

#### Checkpoint: verify the response

A successful response has HTTP status `200`, `object: "chat.completion"`, at least one `choices` entry, and assistant text at `choices[0].message.content`:

```json
{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}
```

> When you request `model: "auto"`, the public response currently preserves the requested ID as `model: "auto"`. Do not use that field as proof of the internal provider or selected upstream model.

If the request returns `401`, confirm that the claimed key was copied exactly. A balance error means the key cannot reserve the request cost; do not retry it in a loop.

#### 4. Pin an explicit model

Open the [live model catalog](https://singular.impossibuild.ai/models) or fetch [pricing JSON](https://api.impossi.build/pricing.json), choose an exact current model ID, and rerun the same request after replacing:

```text
"model": "auto"
```

with:

```text
"model": "provider/live-model-id"
```

**Checkpoint:** the explicit ID must come from the live Singular catalog. A successful response preserves that requested ID in the public `model` field; it still does not prove which physical upstream ultimately served the request.

#### 5. Confirm streaming

```bash
curl -N "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $SINGULAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to three."}]
  }'
```

**Checkpoint:** the response contains data-only SSE frames beginning with `data:` and terminates with `data: [DONE]`. Do not wait for a named Anthropic event or require a final usage-only chunk.

#### Complete the tutorial

You now have a funded key, a verified Chat Completions response, an explicit-model variation, and a working stream.

Next, [connect an SDK or client](https://singular.impossibuild.ai/docs/integrations), review [authentication and key handling](https://singular.impossibuild.ai/docs/authentication), or use the [Chat Completions reference](https://singular.impossibuild.ai/docs/api/chat-completions) while implementing production timeouts, bounded retries, and parameter validation.

---

## How-to guides

Complete a specific integration, key-management, application, or per-call payment task.

### Complete a specific Singular task

Source: https://singular.impossibuild.ai/docs/how-to-guides
Section: How-to guides
Documentation kind: how-to
Maturity: Informational
Keywords: how-to, authentication, integration, BYOK, payments
Related: [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [Connect a client](https://singular.impossibuild.ai/docs/integrations), [Attach provider keys](https://singular.impossibuild.ai/docs/byok), [x402](https://singular.impossibuild.ai/docs/payments/x402), [MPP](https://singular.impossibuild.ai/docs/payments/mpp)

Choose a practical procedure for authentication, clients, provider keys, the web app, or per-call payments.

#### Choose the outcome you need

How-to guides assume you already understand the basic Singular request. Each guide focuses on a concrete result and states any compatibility or deployment boundary that changes the procedure.

| Goal | Guide |
| --- | --- |
| Send credentials safely and manage key lifecycle | [Authenticate requests](https://singular.impossibuild.ai/docs/authentication) |
| Configure an OpenAI SDK or compatible application | [Connect a client](https://singular.impossibuild.ai/docs/integrations) |
| Attach an upstream provider credential | [Attach provider keys](https://singular.impossibuild.ai/docs/byok) |
| Use threads, comparisons, Spaces, and sharing | [Use the chat app](https://singular.impossibuild.ai/docs/app/features) |
| Pay for an eligible call with x402 | [x402 per-call payments](https://singular.impossibuild.ai/docs/payments/x402) |
| Fulfill an advertised MPP charge | [MPP charge payments](https://singular.impossibuild.ai/docs/payments/mpp) |

#### Before following a guide

Use the live catalog for model IDs and the live `402` response for enabled payment methods. A guide describes the shipped contract; it does not turn a deployment-gated rail into an enabled service.

---

### Authenticate API requests

Source: https://singular.impossibuild.ai/docs/authentication
Section: How-to guides
Documentation kind: how-to
Maturity: Stable
Keywords: authentication, Bearer, x-api-key, API key, security
Related: [Quickstart](https://singular.impossibuild.ai/docs/quickstart), [Connect a client](https://singular.impossibuild.ai/docs/integrations), [Billing & usage](https://singular.impossibuild.ai/docs/billing-usage), [x402](https://singular.impossibuild.ai/docs/payments/x402), [MPP](https://singular.impossibuild.ai/docs/payments/mpp)

Send a Singular API key safely, manage its lifecycle, and handle the accountless payment exception.

#### API-key authentication

The recommended header is:

```http
Authorization: Bearer mr_your_key_here
```

The product runtime also accepts:

```http
x-api-key: mr_your_key_here
```

Use one authentication form, not both. The OpenAI SDK sends Bearer authentication. Anthropic SDKs normally send `x-api-key`, but Singular has limited native Anthropic Messages compatibility; see the compatibility guide before using an Anthropic SDK.

#### Key lifecycle

- Create, list, and revoke programmatic keys in [Settings → API keys](https://singular.impossibuild.ai/settings/api-keys).
- The full secret is shown only in the create response. The UI stores only a display prefix and the gateway key ID.
- A Settings-created key starts with zero balance. Current account checkout funds the account's default runtime key, not an arbitrary Settings-issued key; there is no self-service per-key funding control in this release.
- `read_only` maps to the gateway viewer role and `read_write` maps to the developer role for control-plane permissions. This label is not a spend guard: both roles can authorize inference and consume balance.
- Revocation happens at the gateway before the UI removes the key from the active list.
- A key may still be subject to balance, organization, quota, routing-policy, or provider constraints.

#### Accountless machine payments

On eligible routes, an enabled deployment may accept a settled x402 or MPP payment instead of a Singular API key. The first request intentionally has no API-key header and receives a `402 Payment Required` challenge. A valid payment credential becomes the authorization for that single request.

> A generic `402` does not prove that accountless payment is enabled. Clients must inspect the protocol challenge headers and only continue when they can satisfy one of the advertised methods.

#### Security checklist

- Load keys from a secret manager or server-only environment variable.
- Use separate keys for development, staging, production, and independent services.
- Revoke a key immediately if it appears in a client bundle, log, paste, or repository.
- Do not send legacy `x-portkey-*` routing or guardrail headers on the public product API; the gateway rejects that legacy control path.
- Bound retries so an application cannot multiply spend during upstream incidents.

---

### Connect SDKs and compatible clients

Source: https://singular.impossibuild.ai/docs/integrations
Section: How-to guides
Documentation kind: how-to
Maturity: Informational
Keywords: OpenAI SDK, JavaScript, Python, OpenWebUI, n8n
Related: [Quickstart](https://singular.impossibuild.ai/docs/quickstart), [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [Compatibility matrix](https://singular.impossibuild.ai/docs/api/compatibility)

Connect tools that let you set an OpenAI-compatible base URL and use Chat Completions.

#### Required settings

- Base URL: `https://api.impossi.build/v1`
- API key: your `mr_...` Singular API key
- API style: OpenAI Chat Completions
- Model: `auto` or an exact live Singular model ID

#### Environment variables

Many OpenAI SDK-based tools honor these values:

```bash
export OPENAI_BASE_URL="https://api.impossi.build/v1"
export OPENAI_API_KEY="$SINGULAR_API_KEY"
```

Prefer a tool's explicit custom-base-URL setting when it has one. Environment-variable names vary across clients.

#### OpenAI JavaScript SDK

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SINGULAR_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

const completion = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello from Singular." }],
});

console.log(completion.choices[0]?.message?.content);
```

#### OpenAI Python SDK

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SINGULAR_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

completion = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello from Singular."}],
)
print(completion.choices[0].message.content)
```

#### OpenWebUI and chat frontends

Create an OpenAI connection and set the API base to the Singular base URL. If the client insists on populating its model picker from `GET /v1/models`, add `auto` or an exact model ID manually because non-admin Singular API keys intentionally see an opaque model list.

#### n8n and automation tools

Use an OpenAI Chat Model or OpenAI-compatible credential that supports a custom base URL. Set the node's model field explicitly. Avoid nodes that require the Responses API, Files API, Batch API, or Assistants API.

#### Coding clients

A client is a good fit when it can:

1. Use Chat Completions instead of requiring Responses.
2. Override the OpenAI base URL.
3. Accept a custom model ID.
4. Tolerate the Singular error envelope and opaque `/v1/models` result.

Do not assume that a tool described as 'OpenAI compatible' only uses Chat Completions. Some modern agents require Responses, Files, Realtime, or vendor-specific endpoints and will not work against the stable Singular surface.

#### Anthropic SDK clients

Do not point an Anthropic SDK at the complete routed catalog. Native `/v1/messages` support is provider-specific, while the current NanoGPT/AIsa-backed pool uses an OpenAI-compatible wire. Use the OpenAI client and Chat Completions for Claude-family models in Singular.

#### Integration acceptance test

Before adopting a client, verify one non-streaming request, one streaming request, a `401`, a `429` or mocked retry, model selection, cancellation, and any tool/structured-output feature the client requires.

---

### Bring your own provider key

Source: https://singular.impossibuild.ai/docs/byok
Section: How-to guides
Documentation kind: how-to
Maturity: Limited
Keywords: BYOK, provider key, credentials, billing, rotation
Related: [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [Billing & usage](https://singular.impossibuild.ai/docs/billing-usage), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Attach or replace provider credentials without exposing them to the browser and choose when Singular may use them.

#### Before you attach a key

Create a dedicated upstream-provider key with the narrowest permissions and spend limit that your workload needs. Keep your Singular API key available too: BYOK changes the upstream credential, but it does not replace Singular authentication, policy, metering, or balance checks.

#### 1. Attach the provider credential

1. Open [Settings → BYOK](https://singular.impossibuild.ai/settings/byok) while signed in.
2. Choose the matching provider and paste the newly created upstream key.
3. Save the credential once. Do not paste it into a thread, browser console, support ticket, or client-side environment variable.
4. Reload the page and confirm that the provider shows masked attached state. The full secret must not be returned.

The browser sends a new credential to the server once. The gateway stores the secret; later reads expose only masked metadata, and decryption occurs only inside the gateway request path.

#### 2. Verify a matching request

1. Choose an exact live Singular model ID for that provider; do not use `auto` for this check.
2. Send a small Chat Completions request with your Singular API key.
3. Confirm the Singular response succeeds, then check the upstream provider's usage or audit view for the new request.
4. If no upstream activity appears, treat BYOK selection as unverified. The current UI enable toggle is not an independently enforced backend routing control, and a matching stored credential is only one input to gateway credential selection.

#### 3. Replace and rotate safely

1. Create the replacement key upstream before revoking the old key.
2. Replace the saved credential in Settings and repeat the exact-model verification request.
3. Confirm activity on the new key, then revoke the old key at the upstream provider.
4. Test the expected failure or fallback behavior for an expired, rate-limited, or model-restricted credential.

#### Recover or remove access

Credential deletion is not a verified backend contract in this release. Do not rely on the UI detach control as the final revocation step. Revoke the credential at the upstream provider, confirm it can no longer authenticate there, and remove or replace the masked attachment in Settings.

#### Billing boundary

Settings-created Singular API keys remain on credit billing, so attaching a provider key does not bypass low-balance rejection and can result in both upstream-provider charges and Singular retail credit consumption. Apply spend limits and alerts in both systems.

---

### Work in the chat workspace

Source: https://singular.impossibuild.ai/docs/app/features
Section: How-to guides
Documentation kind: how-to
Maturity: Informational
Keywords: chat, threads, Compare, Spaces, sharing
Related: [How-to guides](https://singular.impossibuild.ai/docs/how-to-guides), [How routing works](https://singular.impossibuild.ai/docs/models-routing), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Start routed threads, compare models, organize work in Spaces, share results, and manage account controls.

#### Start and continue threads

1. Open [a new thread](https://singular.impossibuild.ai/c/new#thread).
2. Select `Auto` for policy-based routing or choose an exact live catalog model.
3. Optionally choose Search, Think, or Canvas, then send the prompt.
4. Wait for streaming to complete and verify the answer, requested model label, and any available cost, latency, or citation details.

Use copy, retry, or regenerate when you want a fresh answer. Editing an earlier message creates a fork; use the branch controls to move between sibling paths without rewriting the original history.

#### Compare two to four models

1. Open the [Compare workspace](https://singular.impossibuild.ai/compare).
2. Select two to four models, enter one prompt, and start the run.
3. Inspect each independent stream, citation set, cost, and latency; stop an individual column if needed.
4. Export the comparison as JSON or continue the chosen result into its own thread.

#### Organize work in a Space

1. Open [Spaces](https://singular.impossibuild.ai/spaces) and create a Space.
2. Set its name, description, system prompt, and default model.
3. Start a thread from that Space and confirm the default model and Space instructions are applied.
4. Return to the Space to filter its threads, review citations, or pin available asset metadata.

Space instructions take precedence over account-level custom instructions for a thread inside that Space.

#### Share a frozen snapshot

1. Open the thread you want to publish and choose Share.
2. Copy the generated unguessable public URL and open it in a signed-out window to verify the read-only view.
3. Share that URL only with the intended audience. Later edits to the source thread do not silently rewrite the frozen snapshot; create a new share when the published content must change.

A signed-in reader can fork a shared snapshot into their own account.

#### Find and maintain prior work

Use the [Library](https://singular.impossibuild.ai/library) to search and filter threads by archive state, model, Space, date, citations, or tags. Select rows for bulk archive, restore, move, tag, or delete actions; use CSV export when you need an offline inventory.

#### Understand app modes

Search, Think, and Canvas are Singular app instructions layered onto the request, not universal provider APIs. Search can render citations when supplied, Think requests a reasoning-oriented presentation, and Canvas requests artifact-oriented HTML or code. Do not infer that every catalog model implements a native tool merely because a mode is selectable.

#### Product/API boundary

The browser talks to internal `/api/web/*` backend-for-frontend routes. Those routes are not a public developer API or compatibility promise. Programmatic integrations must use the canonical Singular API origin documented in the quickstart.

---

### x402 per-call payments

Source: https://singular.impossibuild.ai/docs/payments/x402
Section: How-to guides
Documentation kind: how-to
Maturity: Deployment gated
Keywords: x402, payment, 402, USDC, settlement
Related: [MPP](https://singular.impossibuild.ai/docs/payments/mpp), [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [Billing & usage](https://singular.impossibuild.ai/docs/billing-usage), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Understand Singular's x402 v2 handshake, request binding, response headers, and current release gates.

#### Availability

Singular includes x402 v2 payment middleware for `POST /v1/chat/completions` and `POST /v1/embeddings`. It is disabled unless the deployment enables x402. Configuration, verifier selection, startup grace, quote storage, and settlement health are separate readiness checks: a configured or advertised rail is not proof that a payment will settle, and unavailable quote storage can produce `503`.

Only Chat Completions is otherwise documented as a stable inference endpoint today. Do not infer that embeddings is production-ready merely because payment middleware is registered on its route.

A pay-per-call request must use exactly one explicit live-catalog `model`, omit the Singular-specific `models` fallback array, avoid Singular routing suffixes, and set `stream: false`. `model: "auto"`, fallback arrays, suffixed IDs, and streaming are rejected on the payment path.

> The live `402` response is the source of truth for what is advertised. If a request does not include a valid `PAYMENT-REQUIRED` challenge with an acceptable scheme, network, asset, amount, destination, and expiry, the client must treat x402 as unavailable. A challenge proves configuration, not final settlement.

#### 1. Request a quote

Send the exact JSON request without `Authorization`, `x-api-key`, or a payment signature:

```bash
curl -i https://api.impossi.build/v1/chat/completions \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "provider/explicit-model",
    "stream": false,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

When a rail is advertised, the gateway returns `402 Payment Required`, `Cache-Control: no-store`, a JSON x402 v2 `PaymentRequired` body, and the same document encoded in `PAYMENT-REQUIRED`.

#### 2. Parse the v2 challenge

The emitted document follows this shape. This example is illustrative; sign the exact entry returned by the gateway and never reconstruct or drop fields:

```json
{
  "x402Version": 2,
  "error": "payment_required",
  "resource": {
    "url": "https://api.impossi.build/v1/chat/completions",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "<advertised scheme: exact or upto>",
    "network": "<CAIP-2 network>",
    "asset": "<asset identifier>",
    "amount": "<integer base units>",
    "payTo": "<destination>",
    "maxTimeoutSeconds": 30,
    "extra": {
      "rail": "x402",
      "chainId": "<chain id or null>",
      "nonce": "<quote nonce>",
      "bodyHash": "<bound request hash>",
      "expiresAt": "<timestamp>",
      "resource": "<canonical request URL>",
      "description": "<model id>",
      "mimeType": "application/json"
    }
  }]
}
```

x402 v2 uses `amount`. Older examples using `maxAmountRequired` are not valid for this contract.

#### 3. Sign and retry

Use a current x402 client that supports the advertised scheme and network. Retry the same method, URL, explicit model, and JSON content with:

```http
PAYMENT-SIGNATURE: <base64-encoded x402 v2 PaymentPayload>
```

The quote is bound to its nonce, expiry, endpoint, model, JCS-canonical body hash, network, asset, destination, amount, and scheme. JSON key order and insignificant whitespace may change without changing the canonical hash, but semantic request changes invalidate the credential.

#### 4. Read the result

A successfully settled and served `2xx` response includes:

```http
PAYMENT-RESPONSE: <base64-encoded settlement response>
Cache-Control: private
```

For EVM `upto`, inference can complete before deferred settlement. If that settlement fails, Singular deliberately serves the upstream `2xx` without `PAYMENT-RESPONSE` and the operator absorbs the cost. Clients must treat a `2xx` without this header as served but not receipt-confirmed.

A payment failure can return another `402` without a fresh challenge. Do not assume that every post-signature failure is safely replayable.

#### Current standards gate

The source currently selects `upto` for non-streaming EVM chat, but the current official x402 EVM `upto` scheme is Permit2-only and excludes EIP-3009. Singular's implementation does not yet publish the current Permit2-specific requirement fields. There is no separate runtime release gate for this mismatch: enabling x402 can advertise EVM `upto` automatically. Do not enable EVM-chat x402 in production until the implementation is updated and verified against the live facilitator.

Singular's exact path also settles before model execution, while the current default exact scheme describes verify → resource → settle unless an alternate flow is declared. Treat protocol-version alignment as a release gate, not a documentation detail.

#### What x402 does not do here

- It does not top up a Singular API key or reseller wallet.
- It does not apply to native Anthropic Messages, Responses, legacy completions, media routes, or streaming.
- It does not provide a documented automatic-refund guarantee.
- A configured network template is not proof that facilitator support, destination health, and settlement are live.

Primary protocol references: [x402 v2 schema](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) and [x402 HTTP transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md).

---

### MPP charge payments

Source: https://singular.impossibuild.ai/docs/payments/mpp
Section: How-to guides
Documentation kind: how-to
Maturity: Deployment gated
Keywords: MPP, HTTP Payment, USDC, EVM, Solana, Stellar
Related: [x402](https://singular.impossibuild.ai/docs/payments/x402), [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [Billing & usage](https://singular.impossibuild.ai/docs/billing-usage), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Use the HTTP Payment challenge flow and understand the Singular-specific USDC methods and chain requirements.

#### Status and scope

Singular implements MPP-style per-call **charge** challenges on `POST /v1/chat/completions` and `POST /v1/embeddings` when enabled. A paid request must contain exactly one explicit live-catalog `model`, omit `models`, and avoid Singular routing suffixes. Streaming, `model: "auto"`, fallback arrays, suffixed IDs, native Anthropic Messages, legacy completions, Responses, and media routes are excluded.

MPP is a separate HTTP authentication protocol from x402. MPP offers are sent as `WWW-Authenticate: Payment ...` challenges and do not appear inside x402's `accepts` array.

> The HTTP Payment specification is still a working draft, and Singular's `imr*` method names and payloads are private extensions. A generic MPP client will not automatically know how to fulfill them.

#### 1. Receive a Payment challenge

Send the same unsigned, non-streaming, single-model request used for the x402 discovery step. A ready MPP deployment appends one challenge per usable method/network:

```http
HTTP/1.1 402 Payment Required
Cache-Control: no-store
WWW-Authenticate: Payment realm="impossi-router", id="<quote-id>", method="imrevmusdc", intent="charge", ...
```

The challenge binds the quote ID, method, expiry, digest, and request metadata. The digest is SHA-256 over the raw request body. Preserve the exact body bytes for the retry.

#### 2. Fulfill the advertised method

The shipped methods are:

| Method | Family | Fulfillment |
| --- | --- | --- |
| `imrevmusdc` | EVM | Sign an EIP-3009 authorization; Singular's hot relayer submits `transferWithAuthorization`. |
| `imrsolanausdc` | Solana | The payer broadcasts an SPL `TransferChecked` transaction and includes the exact quote nonce in a Memo. |
| `imrstellarusdc` | Stellar | The payer broadcasts a USDC payment operation with the quote nonce as `HashMemo`; the destination must have the required trustline. |

All shipped Singular payment methods are exact-charge methods. Network, asset, destination, amount, memo/nonce, and expiry must match the challenge.

#### 3. Retry with the credential

Encode the method-specific credential as unpadded base64url JSON and retry the exact request:

```http
Authorization: Payment <base64url-without-padding JSON>
Content-Type: application/json
```

Singular verifies the quote and request binding before promoting the settled payment into the data-plane authorization context. Payment headers are stripped before the model request reaches an upstream provider.

#### 4. Read the receipt

A successfully served `2xx` response includes an unpadded base64url receipt:

```http
Payment-Receipt: <base64url-without-padding JSON>
Cache-Control: private
```

Singular never emits `Payment-Receipt` on a non-2xx model response. A quote can still be consumed after settlement even when upstream inference fails, so clients must not equate 'no receipt' with 'no funds moved.'

#### Deployment requirements

MPP defaults off. A working deployment needs MPP enabled, complete chain rows, a durable quote/nonce store, and chain-specific verifier health. EVM methods also require a funded hot relayer. Solana and Stellar use payer-broadcast transactions and enforce their memo bindings.

The default source registry contains network templates, not a promise of live service. Always use the methods and networks actually advertised in the current response.

#### Known protocol deviations

The initial challenge and successful receipt broadly follow the current HTTP Payment draft. Ordinary protocol or payment rejections currently use a bare JSON `402` without the fresh `Payment` challenge and Problem Details described by the draft. Missing verifiers can return `503`, and unexpected verifier failures can surface as `5xx`. Clients should treat failure recovery as Singular-specific and avoid automatic replay.

No first-party `@impossi/router-sdk` is published in this repository. Implementations must use the wire contract and method-specific signing logic; copied placeholder SDK examples are not supported.

Primary references: [HTTP Payment authentication draft](https://paymentauth.org/draft-httpauth-payment-00.html) and [USDC charge method draft](https://paymentauth.org/draft-usdc-charge-00.html).

---

## Reference

Find exact request fields, compatibility, routing, streams, billing, and limitations.

### Reference the Singular contract

Source: https://singular.impossibuild.ai/docs/reference
Section: Reference
Documentation kind: reference
Maturity: Informational
Keywords: reference, API contract, compatibility, errors, billing
Related: [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [Compatibility matrix](https://singular.impossibuild.ai/docs/api/compatibility), [Streaming & errors](https://singular.impossibuild.ai/docs/streaming-errors), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Find exact endpoints, request fields, routing controls, streams, billing behavior, limitations, and agent-readable sources.

#### Use reference for exact answers

Reference pages describe the current Singular contract without assuming full compatibility from an endpoint name. Use them while implementing, debugging, or verifying a client.

| Need | Reference |
| --- | --- |
| Stable request and response fields | [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions) |
| OpenAI, Anthropic, Gemini, and media boundaries | [Compatibility matrix](https://singular.impossibuild.ai/docs/api/compatibility) |
| Singular-specific selection controls | [Routing controls](https://singular.impossibuild.ai/docs/routing-controls) |
| SSE framing, errors, and retries | [Streaming and errors](https://singular.impossibuild.ai/docs/streaming-errors) |
| Prepaid balances, prices, and usage | [Billing and usage](https://singular.impossibuild.ai/docs/billing-usage) |
| Known unsupported or incomplete behavior | [Limitations](https://singular.impossibuild.ai/docs/limitations) |
| Agent-readable indexes and full corpus | [LLM-readable documentation](https://singular.impossibuild.ai/docs/llm-discovery) |

#### Read status literally

Stable applies only to the documented surface. Limited identifies a usable but constrained surface. Deployment gated requires the active deployment to advertise and satisfy the feature. Informational pages organize verified facts without claiming a separate runtime contract.

---

### OpenAI-shaped Chat Completions

Source: https://singular.impossibuild.ai/docs/api/chat-completions
Section: Reference
Documentation kind: reference
Maturity: Stable
Keywords: Chat Completions, OpenAI, messages, tools, JSON
Related: [Compatibility matrix](https://singular.impossibuild.ai/docs/api/compatibility), [Routing controls](https://singular.impossibuild.ai/docs/routing-controls), [Streaming & errors](https://singular.impossibuild.ai/docs/streaming-errors), [Connect a client](https://singular.impossibuild.ai/docs/integrations)

The stable data-plane contract, its supported parameters, response shape, and current compatibility boundaries.

#### Endpoint

```http
POST https://api.impossi.build/v1/chat/completions
Authorization: Bearer <SINGULAR_API_KEY>
Content-Type: application/json
```

#### Minimal request

```json
{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "What makes a good fallback policy?"}
  ]
}
```

`messages` is required. `model` is optional and defaults to `auto`; set an explicit live catalog ID when reproducibility or per-call payment matters. Accepted message roles are `system`, `user`, `assistant`, and `tool`. The current product normalizer does not accept OpenAI's newer `developer` role.

#### Parameter support

| Field | Status | Notes |
| --- | --- | --- |
| `model` | Supported | Optional; defaults to `auto`. Use an exact live catalog ID when reproducibility matters. |
| `messages` | Supported | String content and multimodal content arrays are preserved. |
| `stream` | Supported | OpenAI-style data-only SSE. |
| `max_tokens`, `max_completion_tokens` | Supported | Either field is accepted as the completion limit. Send one. |
| `temperature` | Supported | Provider/model constraints still apply. |
| `top_p` | Supported | Provider/model constraints still apply. |
| `tools` | Limited | Tool definitions reach the first request, but a complete multi-turn tool loop is not fully compatible; see below. |
| `response_format` | Limited | JSON repair is best effort, not a schema-enforcement guarantee. |
| `tool_choice`, `parallel_tool_calls` | Ignored | Not forwarded by the current product normalizer. |
| `stream_options` | Ignored | Do not depend on a final usage-only stream chunk. |
| `stop`, `n`, `seed`, `logprobs`, penalties, `user` | Ignored | Accepted upstream behavior must not be assumed. |
| `modalities`, `audio`, `reasoning_effort` | Ignored | Use model-specific defaults; these controls are not part of the stable contract. |

> Unknown or ignored fields may not produce an error. Build against the supported subset instead of treating a successful HTTP response as proof that every field was honored.

#### Message normalization

Singular retains `role`, `content`, `name`, and `tool_call_id` from input messages. Multimodal content arrays can pass through when the selected backend model accepts them. Assistant `tool_calls` are not preserved on a later request, so the normal OpenAI assistant-tool-tool-result loop is not yet a stable compatibility surface.

#### Response

The non-streaming response is Chat Completions-shaped and includes `choices[].message`, `finish_reason`, and usage where the upstream supplies it.

```json
{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "provider/model-or-auto",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}
```

For privacy and routing abstraction, `model` is rewritten to the requested ID. When the request uses `auto`, it remains `auto`; the public response does not disclose the hidden upstream target.

#### JSON output

`response_format` is forwarded, and Singular may attempt to repair JSON output. This is best effort. Invalid or unrepaired output can still be returned, so applications must parse and validate the result themselves.

#### Calling Claude or Gemini models

Use the exact Claude or Gemini model ID from the live catalog with this OpenAI-shaped endpoint. The wire format remains Chat Completions even when the selected model family is not OpenAI.

```json
{
  "model": "anthropic/<live-model-id>",
  "messages": [{"role": "user", "content": "Hello"}]
}
```

Do not guess a model ID from upstream documentation. Model availability and naming come from the live Singular catalog.

---

### Compatibility, surface by surface

Source: https://singular.impossibuild.ai/docs/api/compatibility
Section: Reference
Documentation kind: reference
Maturity: Informational
Keywords: compatibility, OpenAI, Anthropic, Gemini, media
Related: [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [Connect a client](https://singular.impossibuild.ai/docs/integrations), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Know exactly which OpenAI, Anthropic, Gemini, and media-shaped routes are production-ready.

#### Compatibility matrix

| Protocol surface | Public product-key status | Guidance |
| --- | --- | --- |
| `POST /v1/chat/completions` | **Stable** | Use for text/chat models across the routed catalog. |
| `GET /v1/models` | **Limited** | Authenticated non-admin keys intentionally receive only an opaque `auto` entry. Use the public catalog/pricing feed for discovery. |
| `POST /v1/messages` | **Provider-specific** | Requires a true Anthropic-wire target. It is not a general translation layer across the current NanoGPT/AIsa-backed pool. |
| `POST /v1/messages/count_tokens` | **Not a product-key surface** | Registered legacy handler; do not rely on it. |
| `POST /v1/responses` and Responses resources | **Not a product-key surface** | Use Chat Completions. A route name alone does not establish Responses semantics. |
| `POST /v1/embeddings` | **Not release-ready** | A product handler is registered, but the endpoint-kind wiring does not currently meet the stable contract. |
| Images, audio, rerank, moderation | **Not release-ready** | Registered paths do not currently have a verified end-to-end product model-selection path. |
| Legacy completions, files, batches, fine-tuning, realtime | **Not a product-key surface** | Legacy gateway handlers are intentionally isolated from public product routing. |
| Gemini `generateContent` | **Not implemented** | Gemini-family models are accessed through Chat Completions, not a native Gemini route. |

#### OpenAI SDK compatibility

Point the OpenAI JavaScript or Python client at `https://api.impossi.build/v1` and use `chat.completions.create`. This is the primary supported integration.

Singular does **not** claim full OpenAI platform parity. In particular, Chat Completions support does not imply Responses, Assistants, Files, Batch, Realtime, fine-tuning, or every modern Chat field.

#### Anthropic Messages compatibility

Anthropic's native Messages protocol differs from OpenAI Chat in authentication, request shape, response content blocks, streaming event names, and error envelopes. Singular has a `/v1/messages` product handler, but it can only work when routing selects a provider target with an actual Anthropic Messages wire adapter.

The current NanoGPT/AIsa-backed targets use an OpenAI-compatible wire. For those targets:

- Call Claude-family models through `/v1/chat/completions`.
- Use the OpenAI SDK configuration from the quickstart.
- Do not advertise the Anthropic SDK as a drop-in client for the complete model pool.
- Do not assume native Anthropic named SSE events or Anthropic error envelopes.

#### OpenAI Responses compatibility

OpenAI Responses uses `input`, heterogeneous `output[]`, typed streaming events, and resource lifecycle endpoints. Singular's current public runtime does not implement that contract end to end. Use Chat Completions and read `choices[0].message.content`.

#### Compatibility release gate

A surface moves to Stable only after tests cover its exact path, auth header, required and ignored fields, non-stream response envelope, streaming event protocol, tool-call deltas, usage, errors, rate limits, and current official JavaScript/Python SDK behavior.

---

### Singular request extensions

Source: https://singular.impossibuild.ai/docs/routing-controls
Section: Reference
Documentation kind: reference
Maturity: Limited
Keywords: routing, fallback, provider preferences, profiles, suffixes
Related: [How routing works](https://singular.impossibuild.ai/docs/models-routing), [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Use fallback model lists, routing profiles, provider preferences, and the supported model suffixes.

#### Fallback model list

Singular accepts a `models` array with two or more string IDs. The first valid entry becomes the primary model and the remainder become an ordered fallback list:

```json
{
  "models": [
    "provider/primary-model",
    "provider/first-fallback",
    "provider/second-fallback"
  ],
  "messages": [{"role": "user", "content": "Hello"}]
}
```

This is a Singular extension, not an OpenAI field. A one-item `models` array is ignored; use the standard `model` field when there is no fallback list.

> Accountless x402 and MPP calls do not support this extension. A paid request must contain exactly one explicit live-catalog `model`, omit `models`, and avoid Singular routing suffixes so the quoted model and executed model cannot diverge.

#### Routing profiles

Set `routing_profile` (or `routingProfile`) to one of:

- `eco`: bias policy toward economical eligible candidates.
- `auto`: use the balanced default policy.
- `premium`: bias toward higher-tier eligible candidates.
- `agentic`: bias scoring toward the agentic routing profile. It does not hard-filter eligibility or tool capability.

Profiles are policy inputs, not guarantees that a particular provider or model will be selected.

#### Provider preference object

Advanced callers can place routing preferences in a `provider` object. Supported controls include ordered/only/ignored provider sets, fallback permission, required-parameter checks, zero-data-retention and data-collection constraints, region and quantization filters, price ceilings, and throughput/latency preferences.

```json
{
  "model": "auto",
  "provider": {
    "allowFallbacks": true,
    "sort": "price",
    "zdr": true,
    "maxPrice": {"prompt": 2, "completion": 8}
  },
  "messages": [{"role": "user", "content": "Hello"}]
}
```

A constraint can reduce the candidate pool to zero. Applications must handle a no-eligible-model error instead of silently dropping security or price constraints.

#### Supported model suffixes

Singular recognizes exactly three final suffixes:

| Suffix | Effect |
| --- | --- |
| `:nitro` | Sets the default provider sort to throughput. |
| `:floor` | Sets the default provider sort to price. |
| `:exacto` | Requires parameter compatibility and selects the agentic routing profile. |

Only the last colon-delimited token is inspected. Unknown suffixes remain part of the model ID because some provider models legitimately contain colons. Suffixes such as `:online`, `:thinking`, and `:memory` are not Singular controls in the current product runtime.

#### Precedence

Organization, team, key, and server-side guardrails can narrow or override caller preferences. Body extensions never grant access to a disallowed provider, model, region, data policy, or spend tier.

---

### Streaming, errors, and retries

Source: https://singular.impossibuild.ai/docs/streaming-errors
Section: Reference
Documentation kind: reference
Maturity: Stable
Keywords: streaming, SSE, errors, retries, rate limits
Related: [Quickstart](https://singular.impossibuild.ai/docs/quickstart), [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [Connect a client](https://singular.impossibuild.ai/docs/integrations)

Parse Singular's Chat Completions SSE stream correctly and retry only failures that can reasonably recover.

#### Streaming request

Set `stream: true` on Chat Completions:

```bash
curl -N "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $SINGULAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to three."}]
  }'
```

The response is a data-only Server-Sent Events stream. Each payload is a Chat Completions chunk; partial text is under `choices[].delta.content`. A normal stream ends with:

```text
data: [DONE]
```

`stream_options` is not part of Singular's stable forwarded parameter subset. Do not require OpenAI's optional final usage-only chunk.

#### JavaScript stream

```javascript
const stream = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Count to three." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

#### Python stream

```python
stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Count to three."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")
```

#### Error envelope

Singular-generated API errors commonly use this envelope:

```json
{
  "status": "failure",
  "code": "too_many_requests",
  "message": "Too many requests",
  "retryAfterSeconds": 30
}
```

Sanitized upstream failures can instead preserve an OpenAI-shaped `{"error":{"message":"...","type":"...","code":"..."}}` object, while some middleware validation failures use the shorter `{"status":"failure","message":"..."}` form. Clients must branch on HTTP status first and tolerate either family, a missing `code`, or a short `400` body.

| HTTP status | Meaning | Retry? |
| --- | --- | --- |
| `400` / `422` | Invalid request or unsupported shape | No; fix the request. |
| `401` | Missing or invalid key | No; replace credentials. |
| `402` | Payment or balance action required | No blind retry; satisfy the advertised challenge or fund the key. |
| `403` | Revoked key or authenticated caller not permitted | No; replace the key or change policy/balance. |
| `404` | Unknown resource or unavailable surface | No. |
| `408` | Request timeout | Usually, with a bound. |
| `429` | Rate limited | Yes; honor `Retry-After`. |
| `5xx` | Singular service or upstream failure | Usually, with exponential backoff and jitter. |

A `401` response includes `WWW-Authenticate: Bearer`. A `429` may include `Retry-After`; the gateway supplies a fallback value when a more specific limit does not.

#### Retry pattern

```python
import random
import time
from openai import APIStatusError, RateLimitError

def call_with_retry(call, attempts=5):
    for attempt in range(attempts):
        try:
            return call()
        except (RateLimitError, APIStatusError) as error:
            status = getattr(error, "status_code", None)
            if status not in (408, 429, 500, 502, 503, 504) or attempt == attempts - 1:
                raise
            time.sleep((2 ** attempt) + random.random())
```

Use an application-level idempotency strategy before retrying workflows that trigger side effects outside the model call.

---

### Prepaid billing, pricing, and usage

Source: https://singular.impossibuild.ai/docs/billing-usage
Section: Reference
Documentation kind: reference
Maturity: Stable
Keywords: billing, prepaid, pricing, usage, balance
Related: [Authenticate requests](https://singular.impossibuild.ai/docs/authentication), [How routing works](https://singular.impossibuild.ai/docs/models-routing), [Attach provider keys](https://singular.impossibuild.ai/docs/byok), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Understand the live retail price source, balance-backed requests, and the difference between authoritative totals and UI estimates.

#### Prepaid model

The consumer product uses prepaid credit rather than subscription seats. A successful metered request reserves and captures cost against the applicable balance or wallet according to the key and organization configuration.

For a standalone developer key, [`/topup`](https://api.impossi.build/topup) creates a funding session and reveals the newly funded key once at `/claim`. Signed-in account checkout instead funds the account's default runtime key. It does not fund a separately issued Settings key.

Use the [Pricing page](https://singular.impossibuild.ai/pricing) for human browsing and [`https://api.impossi.build/pricing.json`](https://api.impossi.build/pricing.json) for machine-readable retail rates.

#### Token-cost formula

For a standard text request, the public estimate is:

```text
cost = (prompt_tokens × prompt_rate_per_million / 1,000,000)
     + (completion_tokens × completion_rate_per_million / 1,000,000)
```

Model-specific cached-token, reasoning-token, per-request, media, or upstream billing behavior can differ. The settled gateway event is authoritative, not a client-side estimate.

#### Account views

- [Billing](https://singular.impossibuild.ai/settings/billing) shows the authenticated key's authoritative balance and rolling use, available promotional or affiliate credit lots, and top-up controls.
- [Usage](https://singular.impossibuild.ai/settings/usage) shows authenticated-key-scoped gateway totals plus app-derived model and space views and CSV export. It is not an account-wide aggregation across every key.
- Current consumer funding history is intentionally empty when the gateway cannot provide a safe key-scoped history; the UI does not fabricate it.

#### Authoritative versus estimated data

The authenticated key's balance and recent spend total come from the gateway's money source of truth. UI time-series and per-model groupings are derived from app-stored messages, and the Space selector samples those daily points rather than filtering an authoritative gateway dimension. Read them as estimates. Reconciliation-sensitive workflows should use gateway settlement records or operator reports.

#### Zero-price rows

Do not treat every zero-looking catalog row as free. The storefront currently normalizes unavailable values, so zero can also represent unknown or on-request pricing. Only a clearly published positive rate or explicit free designation should drive automated spend decisions.

#### Low-balance behavior

A request can be rejected when the key or backing wallet cannot reserve the required ceiling. Do not repeatedly retry a balance error. Top up the key or satisfy an advertised accountless payment challenge. Attaching a BYOK credential through Settings does not currently bypass the Singular credit balance requirement.

---

### Current limits and honest boundaries

Source: https://singular.impossibuild.ai/docs/limitations
Section: Reference
Documentation kind: reference
Maturity: Informational
Keywords: limitations, unsupported, partial, release readiness
Related: [Compatibility matrix](https://singular.impossibuild.ai/docs/api/compatibility), [Routing controls](https://singular.impossibuild.ai/docs/routing-controls), [Attach provider keys](https://singular.impossibuild.ai/docs/byok), [x402](https://singular.impossibuild.ai/docs/payments/x402), [MPP](https://singular.impossibuild.ai/docs/payments/mpp)

What is implemented, what is partial, and which attractive-looking UI or route surfaces are not release-ready.

#### API limitations

- Stable public compatibility is OpenAI-shaped Chat Completions, not the complete OpenAI platform.
- Responses, native Gemini, files, batches, fine-tuning, realtime, and legacy completions are not product-key surfaces.
- Native Anthropic Messages is provider-specific and does not translate the current NanoGPT/AIsa OpenAI-wire pool.
- Embeddings, image generation, audio, rerank, and moderation routes are registered but do not have a verified stable end-to-end product path.
- The `developer` message role and many newer Chat parameters are not forwarded.
- Full multi-turn tool-call compatibility is incomplete because assistant `tool_calls` are not preserved on the follow-up request.
- Structured output repair is best effort; applications must validate JSON themselves.
- Non-admin `/v1/models` is intentionally opaque and returns `auto` rather than the full internal registry.
- Settings BYOK is limited: detach and enable-toggle semantics are not enforced end to end, and attached credentials do not bypass Singular credit billing.

#### Payment limitations

- x402 and MPP default off and require a live deployment configuration and healthy verifiers.
- Payment requests require an explicit model and non-streaming request.
- Native Anthropic Messages and Responses cannot be paid through these per-call paths.
- Current x402 EVM `upto` behavior needs alignment with the current Permit2-based specification before release.
- MPP `imr*` methods are Singular-specific extensions with no published first-party client in this repository.
- No current test proves a real wallet → live facilitator/on-chain settlement → inference → receipt round trip; unit tests mock external settlement.
- Per-call payment is not a key-balance or reseller-wallet top-up and has no documented automatic-refund guarantee.

#### App limitations

- File attachments can be selected and previewed, but the active thread stream currently sends an empty attachment list; file bytes do not reach inference.
- Voice UI records elapsed time and submits a text placeholder rather than audio content.
- Space asset creation stores metadata and a placeholder URL; it is not a complete upload/retrieval pipeline.
- Media 'Regenerate' is currently a UI stub.
- Message likes and Library pin state are not fully account-synced.
- Consumer funding history remains empty when no safe key-scoped source exists.
- Account export downloads JSON immediately; it is not a ZIP delivered by email.
- Anonymous guest issuance requires Turnstile integration in production and should not be advertised as universally available until the active deployment includes that UI path.

#### Catalog limitations

The storefront feed is reliable for model ID, provider/name presentation, positive retail prices, and positive context values. Missing price, modality, BYOK, capability, and latency fields may be normalized or defaulted. Do not use them as definitive model capability evidence.

#### Release principle

Documentation follows verified behavior, not aspirational route names. A feature should move out of this page only after source wiring, contract tests, and a live smoke agree.

---

### Documentation for agents and crawlers

Source: https://singular.impossibuild.ai/docs/llm-discovery
Section: Reference
Documentation kind: reference
Maturity: Informational
Keywords: llms.txt, agents, crawlers, Markdown, discovery
Related: [Reference](https://singular.impossibuild.ai/docs/reference), [Compatibility matrix](https://singular.impossibuild.ai/docs/api/compatibility), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Use the concise index for discovery and the full text bundle when a task genuinely needs the complete contract.

#### Available files

- [`/llms.txt`](https://singular.impossibuild.ai/llms.txt): curated product and developer entrypoint.
- [`/llms-full.txt`](https://singular.impossibuild.ai/llms-full.txt): all documentation pages concatenated as Markdown.
- [`/docs/llms.txt`](https://singular.impossibuild.ai/docs/llms.txt): technical documentation index.
- [`/docs/llms-full.txt`](https://singular.impossibuild.ai/docs/llms-full.txt): complete technical corpus.

The two full endpoints intentionally contain the same canonical documentation corpus. The two indexes differ in orientation: the root index starts at the product level, while the docs index starts at the API contract.

#### Agent guidance

1. Load the smallest relevant page set first.
2. Use the full bundle only for broad audits, migrations, or offline ingestion.
3. Fetch the live pricing JSON before selecting or quoting a model.
4. Treat each compatibility surface independently.
5. Treat a live payment challenge, not static prose, as proof of an enabled rail.
6. Separate read-only discovery from actions that create keys, spend balance, settle payments, replay traces, or mutate operator state.

#### Formats

The LLM files are UTF-8 `text/plain` containing Markdown. Human documentation pages are HTML. A public OpenAPI specification is not published in this release; agents must not invent schemas for routes absent from the compatibility matrix.

#### Freshness

This documentation snapshot was updated on 2026-08-10. Live model availability, rates, balance, provider health, and payment rails can change independently and must be checked at request time.

---

## Explanation

Understand model identity, automatic routing, fallbacks, and role-gated platform boundaries.

### Understand why Singular behaves this way

Source: https://singular.impossibuild.ai/docs/explanation
Section: Explanation
Documentation kind: explanation
Maturity: Informational
Keywords: explanation, routing model, providers, partners, operators
Related: [How routing works](https://singular.impossibuild.ai/docs/models-routing), [Partner and operator roles](https://singular.impossibuild.ai/docs/platform/partners), [Reference](https://singular.impossibuild.ai/docs/reference)

Build a mental model of routing, model identity, provider fallbacks, and the boundary between public and role-gated surfaces.

#### Build the right mental model

Explanation pages connect implementation details into a coherent view of Singular. Read them when exact field definitions are not enough to explain model identity, automatic selection, fallbacks, or commercial control-plane boundaries.

Start with [how models and routing work](https://singular.impossibuild.ai/docs/models-routing) to understand the live catalog, explicit IDs, Auto routing, provider health, and ordered fallbacks.

Read [partner and operator roles](https://singular.impossibuild.ai/docs/platform/partners) to understand why reseller, white-label, affiliate, and operator workflows remain separate from the public inference API.

#### Use explanation with reference

Explanation describes why the system is shaped this way. Use the [reference section](https://singular.impossibuild.ai/docs/reference) for exact endpoints, accepted fields, statuses, and error behavior.

---

### How models and routing work

Source: https://singular.impossibuild.ai/docs/models-routing
Section: Explanation
Documentation kind: explanation
Maturity: Stable
Keywords: models, routing, auto, fallback, provider health
Related: [Routing controls](https://singular.impossibuild.ai/docs/routing-controls), [Chat Completions](https://singular.impossibuild.ai/docs/api/chat-completions), [Billing & usage](https://singular.impossibuild.ai/docs/billing-usage)

Understand the live catalog, explicit and automatic model selection, provider health, and fallback behavior.

#### Discover models

Use the [public model catalog](https://singular.impossibuild.ai/models) for browsing and [`https://api.impossi.build/pricing.json`](https://api.impossi.build/pricing.json) for machine-readable retail IDs, positive rates, and context values.

```bash
curl https://api.impossi.build/pricing.json
```

The pricing response is a timestamped snapshot:

```json
{
  "as_of": "<ISO-8601 timestamp>",
  "models": [{
    "id": "provider/model",
    "name": "Display name",
    "promptPerMillionUsd": 1.0,
    "completionPerMillionUsd": 4.0,
    "maxContextTokens": 131072
  }]
}
```

Model availability changes. Never hardcode a copied catalog as permanent truth.

#### Pricing metadata cautions

- Positive input/output rates are retail USD per one million tokens.
- A missing or zero-looking value in the storefront feed must not automatically be interpreted as free; it may mean pricing is unavailable or on request.
- Context values are useful when present, but model-specific behavior should still be tested.
- Storefront modality, capability, BYOK, and latency fields may be fallback values and are not a protocol guarantee.

#### Explicit model selection

For repeatable behavior, send the exact catalog ID:

```json
{
  "model": "provider/model",
  "messages": [{"role": "user", "content": "Hello"}]
}
```

The prefix is part of the Singular model ID. It is not necessarily a disclosure of the physical upstream that ultimately serves the request.

#### Automatic routing

Use `model: "auto"` when policy-based selection matters more than pinning one exact model. The runtime scores eligible candidates using configured policy, availability, health, pricing, and latency signals. Ordered fallback is narrower than general failure recovery: the explicit `models` list advances on rate-limit, service-unavailable, or context-length failures, not on every execution error.

The public response deliberately preserves the requested `model` value. It does not expose internal routing rationale to non-admin callers.

#### Authenticated `/v1/models`

The OpenAI-shaped models route exists, but non-admin product keys intentionally receive an opaque catalog containing only `auto`. That privacy boundary prevents public callers from using the admin registry as a provider-discovery channel. Use `/pricing.json` for the public retail model list.

#### Provider health and fallbacks

Provider health, cooldowns, key priority, and fallback order are gateway concerns. Applications should still use timeouts and bounded retries because a final error can mean the eligible upstream pool was exhausted or the request failed outside the retryable path.

---

### How partner and operator roles work

Source: https://singular.impossibuild.ai/docs/platform/partners
Section: Explanation
Documentation kind: explanation
Maturity: Limited
Keywords: partner, affiliate, reseller, white-label, operator
Related: [Explanation](https://singular.impossibuild.ai/docs/explanation), [Use the chat app](https://singular.impossibuild.ai/docs/app/features), [Limitations](https://singular.impossibuild.ai/docs/limitations)

Understand the role-gated commercial and control-plane surfaces without confusing them with the public model API.

#### Availability

> These role-gated surfaces depend on the active backend deployment and account provisioning. The frontend exposes the workflows described here, but production backend reachability was not independently verified in this documentation pass. Treat the signed-in Partner page and its role responses as the live source of truth.

#### Partner onboarding

The [Partner page](https://singular.impossibuild.ai/partner) adapts to the signed-in user's role. Affiliate enrollment is self-service. Reseller access uses an application and operator approval workflow. These account workflows are separate from data-plane API authentication.

#### Affiliate workspace

Affiliates can create and share referral codes and see uses, referred accounts, lifetime earned credit, spendable earned credit, and expiring credit lots. Rewards are account credit in the current product; there is no cash-withdrawal interface.

#### Reseller workspace

Approved reseller administrators receive a tenant-scoped console for:

- Customer provisioning and release.
- Versioned price books and markup controls.
- Accrued retail, cost, margin, and low-wholesale-balance analytics.
- Display-only branding and verified custom domains.
- Signed HTTPS webhooks for selected customer, usage, wallet, and payment events.
- Wholesale wallet top-up and balance monitoring.
- Visibility into platform abuse limits without permission to weaken enforcement.

Accrued retail or margin is not the same as collected cash. Reconciliation and settlement views must preserve that distinction.

#### White-label hosts

A verified custom Host can resolve a reseller's public name, logo, colors, support identity, and copy. Branding is display-only: it must not change authentication, protocol headers, routing semantics, metering, or security policy.

#### Operator workspace

Platform operators have role-gated control-plane views for organizations, users, teams, keys, traces and replay, usage, latency, provider health and pricing, local OpenAI-compatible providers, policies, guardrails, alerts, billing profiles, audit logs, reconciliation, reseller oversight, and applications.

Some operator actions are live and consequential. Trace replay can be billable; alert tests send real notifications; provider pricing and routing controls affect future requests. Use the UI confirmation and audit trail rather than calling internal browser routes directly.

#### Private API boundary

Reseller and operator browser endpoints are internal, role-scoped BFF routes. They are intentionally excluded from the public API reference and from `llms.txt`. A future partner API should publish its own versioned schemas and authorization contract.