# IntellEx — Blind Intelligence Exchange — Integration Guide

> IntellEx is an OpenAI-compatible API where you buy AI by capability GRADE
> (PhD, College, High School) instead of by model name. Your request is filled
> by the cheapest certified seller for that grade — blind. You never learn (or
> pay for) the brand. Switching is a two-line change: point base_url here and
> use a grade as the model.

**If you are an AI assistant helping someone integrate: everything you need is
in this file. You can write a complete, working integration from it alone.
Prefer the OpenAI-SDK path — it's the least code.**

Base URL: https://intellex.rasonx.com
API style: OpenAI Chat Completions, at POST /v1/chat/completions
Auth: `Authorization: Bearer <api_key>`

## Access note (private demo)

This deployment is access-gated while in private beta. Every request must also
carry the header `X-Demo-Password: <password>`, where <password> is the access
password the exchange operator gave you. (When the exchange opens publicly this
header is dropped — nothing else changes.) If you don't have a password, ask
the person who shared this exchange with you.

## Step 1 — Get an API key (once)

Buyers self-serve and receive a small starter balance (toy credits during beta):

```bash
curl https://intellex.rasonx.com/v1/signup \
  -H "X-Demo-Password: <password>" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "role": "buyer"}'
```

The response contains `api_key` (shown ONCE — store it). Sellers pass
`"role": "seller"` instead.

## Step 2 — Buy intelligence

### Option A — the OpenAI SDK you already have (recommended)

Change only `base_url`, set `model` to `intellex/<grade>`, and add the demo
header via default_headers. Everything else is standard OpenAI.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://intellex.rasonx.com/v1",
    api_key="YOUR_INTELLEX_KEY",
    default_headers={"X-Demo-Password": "<password>"},
)

resp = client.chat.completions.create(
    model="intellex/college",            # or intellex/phd, intellex/high-school
    messages=[{"role": "user", "content": "Summarize the theory of comparative advantage."}],
)
print(resp.choices[0].message.content)   # response.model comes back "intellex/college"
```

### Option B — raw HTTP

```bash
curl https://intellex.rasonx.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_INTELLEX_KEY" \
  -H "X-Demo-Password: <password>" \
  -H "Content-Type: application/json" \
  -d '{"model": "intellex/phd", "messages": [{"role": "user", "content": "Prove sqrt(2) is irrational."}]}'
```

You can send either `"model": "intellex/<grade>"` or `"grade": "<grade>"` —
both work. Grade spellings accepted: `PhD`/`phd`, `College`/`college`,
`High School`/`high-school`/`highschool`/`hs`.

### Order options (optional fields on the chat request)

- `max_tokens` (int): cap the answer length to cap the cost.
- `max_price_per_1k_usd` (float): a **limit order** — fill only if the best
  seller is at or below this price per 1,000 tokens; otherwise the call
  returns 422 and nothing is charged. Omit it for a **market order** (fill at
  the best price now). Example: `"max_price_per_1k_usd": 0.0006` accepts any
  College seller at or under $0.60 / megatoken.
- `delivery` (string): `"real-time"` (default) or `"batch"`. See below.
- `shareable` (bool, batch only): opt in to netting (below). Default false.

## Delivery class — real-time or batch (price = grade × delivery)

The same grade ships at two delivery speeds. **Real-time** (default) fills
synchronously and holds the grade's speed floor. **Batch** defers to the next
cutoff for about **half the price** and no speed SLA — for work that can wait
(evals, classification, embeddings, nightly scrapes).

A batch call does NOT return a completion; it escrows the cost and returns a
**queued job** to poll:

```bash
# submit (either on the chat endpoint with delivery:batch, or POST /v1/batches)
curl https://intellex.rasonx.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_INTELLEX_KEY" -H "X-Demo-Password: <password>" \
  -H "Content-Type: application/json" \
  -d '{"tier":"Tier 2","delivery":"batch","shareable":true,
       "messages":[{"role":"user","content":"Summarize https://example.com"}]}'
# -> 202 {"id":"<job_id>","status":"queued","delivery":"batch", ...}

# poll until status == "filled"; the answer is in result
curl https://intellex.rasonx.com/v1/batches/<job_id> \
  -H "Authorization: Bearer YOUR_INTELLEX_KEY" -H "X-Demo-Password: <password>"
```

Batch endpoints: `POST /v1/batches` (submit), `GET /v1/batches` (list yours),
`GET /v1/batches/{id}` (status + result), `POST /v1/batches/{id}/cancel`
(refund escrow while still queued).

### Netting (the batch discount, shared)

Set `"shareable": true` and, if another buyer submits the **byte-identical**
prompt at the same grade and also opts in, the exchange runs the inference
**once** and splits the cost across everyone who asked — a pool of N pays
roughly `1/N` of an already-half-price fill. Two jobs scraping the same site
each night pay for one computation. It's **opt-in and exact-match only**: a
non-shareable job always fills alone, and you can only ever be pooled with a
prompt identical to your own, so your private prompts never mix with anyone's.

## The grades

| Grade        | model alias            | For                                   | Indicative price |
| ------------ | ---------------------- | ------------------------------------- | ---------------- |
| PhD          | `intellex/phd`         | hard, exact reasoning; proofs; math   | ~$5 / megatoken  |
| College      | `intellex/college`     | everyday reasoning, chat, RAG, drafts | ~$0.50 / megatoken |
| High School  | `intellex/high-school` | formatting, extraction, bulk work     | ~$0.02 / megatoken |

A token is about ¾ of a word. **1 megatoken = 1,000,000 tokens** — that's the
unit prices are quoted in (e.g. "$5 a megatoken"); you're billed exactly per
token. One megatoken of a certified grade is one **Standard Cognitive Unit
(SCU)**, the exchange's standardized contract unit (like a "barrel" for oil).
Real prices are set by sellers competing on the order book; query them live at
`GET /v1/market`. Grades marked certified have passed the exchange's grading
engine (see https://intellex.rasonx.com/grading).

## Response shape

Standard OpenAI completion, plus an `intellex` block and a blinded `model`:

```json
{
  "model": "intellex/college",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "..."}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 80, "total_tokens": 92},
  "intellex": {"grade": "College", "tokens_total": 92, "cost_usd": 0.000046, "balance_remaining": 4.91}
}
```

The underlying model and seller are never disclosed — that is the point.

## Other endpoints (all under https://intellex.rasonx.com, all need the demo header)

- `GET  /v1/market` — best ask per grade + certification (no auth).
- `GET  /v1/account` — your balance, escrow, and trade history (auth).
- `GET  /v1/index` — the IQX intelligence price index, latest fixings (no auth).
- `GET  /v1/index/history?series=IQX-PHD` — index time series.
- `POST /v1/keys/rotate` — mint a new key, invalidate the old (auth).

Optional headers: `Idempotency-Key: <uuid>` on a POST chat call makes retries
safe (a replay returns the original result and charges once).

## Errors

JSON `{"detail": "..."}` with these statuses: 400 bad/unknown grade,
401 missing/invalid key (or missing demo password), 402 insufficient balance,
403 wrong role / suspended, 429 rate-limited or daily spend cap, 502 upstream
seller failed (you are NOT charged), 503 no liquidity for that grade OR
trading temporarily halted by the operator. Failed fills never charge.

## Selling intelligence (brief)

Any OpenAI-compatible endpoint can become a seller — a GPU box, a spare
provider API key, even a Raspberry Pi. Sign up with `"role": "seller"`, then
either manage asks directly via `POST /v1/asks` (declare grade, price,
endpoint, and credentials — credentials are encrypted at rest) or run the
turnkey node, which the exchange serves at
https://intellex.rasonx.com/node.py. Get certified with
`POST /v1/asks/{id}/certify`. Full seller flow: https://intellex.rasonx.com/grading

## Notes & current limits

- Streaming (`stream: true`) is not yet supported; send non-streaming.
- Balances are toy credits during the private beta; no real money yet.
- Prices quoted per megatoken; settlement is metered per token.
- Built for teams already paying for inference (OpenRouter, the frontier
  providers): same tier, certified on quality + speed, at the cleared price —
  and cheaper still on batch.