Skill: nealo/codex-gateway (version 1.0.0)

--- name: codex-gateway description: >- Use when the user wants to query the Codex Supergraph and the server returns a 402 challenge. Pays per query via the MPP 402 challenge flow. Only supports queries, not mutations or subscriptions. metadata: author: codex-data version: "1.0" --- # Codex Machine Payment Protocol (MPP) Use this skill when the Codex Supergraph returns a `402 Payment Required` response. The MPP challenge flow lets you pay per query without needing an API key. | | | | --------------------- | --------------------------------------------------------------- | | HTTP endpoint | `https://graph.codex.io/graphql` | | Credential header | `Authorization: Payment <base64url-credential>` | ## How it works 1. Send a GraphQL query (no credential). 2. Server returns `402 Payment Required` with `WWW-Authenticate: Payment ...` challenges. 3. Client solves one challenge and retries with `Authorization: Payment <credential>`. 4. Server returns GraphQL data + `Payment-Receipt` header. ## Constraints - **Query only.** Mutations and subscriptions return `403` in MPP mode. - If a valid API key or bearer token is also present, API auth takes precedence. ## Rules - Never print raw credentials. - Only use MPP for `query` operations. - **Before constructing any query**, read `references/query-templates.md` below for the correct GraphQL schema. Do not guess query or field names. ## References | File | Purpose | | ---- | ------- | | [../codex-supergraph/references/query-templates.md](../codex-supergraph/references/query-templates.md) | **GraphQL query schema and examples — read before constructing queries** | | [../codex-supergraph/references/gotchas.md](../codex-supergraph/references/gotchas.md) | Common query failure points | | [references/gotchas.md](references/gotchas.md) | MPP-specific failure points | | [rules/wallets.md](rules/wallets.md) | Wallet setup: tempo wallet/request (Tempo) | | [references/mpp-flow.md](references/mpp-flow.md) | Auth matrix, challenge details, error codes |

path: rules/wallets.md
content: # Wallet Reference

The 402 challenge flow requires a funded wallet to sign payment credentials. Which tool to use depends on the network the challenge specifies.

| Network | Tool | Auth method | Currency |
| ------- | ---- | ----------- | -------- |
| Tempo (chain 4217) | `tempo` (`wallet` + `request` extensions) | Passkey via `tempo wallet login` | USDC |

Pick the tool that matches the network in the `WWW-Authenticate` challenge, then follow the corresponding section below.

---

## Tempo — tempo wallet / tempo request

`tempo` is the Tempo CLI. The `wallet` extension manages identity and funding; the `request` extension is an HTTP client that handles the full MPP 402-challenge flow automatically — it detects the challenge, signs a Tempo transaction, and retries the request in one step.

### Install

```bash
curl -fsSL https://tempo.xyz/install | bash
tempo add wallet
```

### Setup

```bash
tempo wallet login
```

This opens a passkey-based auth flow. No private keys to manage.

### Preflight check

```bash
tempo wallet -t whoami
```

Confirm `ready` is `true` and `balance.available` has sufficient USDC before making paid requests.

### Making a paid request

`tempo request` handles the 402 challenge and payment automatically:

```bash
tempo request -t -X POST \
  -H "Content-Type: application/json" \
  --json '{"query":"query { getNetworks { id name } }"}' \
  https://graph.codex.io/graphql
```

### Session management

Sessions open a payment channel on-chain once, then use off-chain vouchers for subsequent requests (no gas per request):

```bash
tempo wallet -t sessions list          # view active sessions
tempo wallet -t sessions close --all   # close all sessions when done
```

### Recovery

| Symptom | Action |
| ------- | ------ |
| `No wallet configured` | Run `tempo wallet login` |
| `Insufficient balance` | Tell the user — wallet needs funding |
| `Spending limit exceeded` | Tell the user — key limit reached |

---

## Rules

- **Never print, log, or read private keys.** Tools handle key management internally.
- **Always run a preflight check** before attempting paid requests.
- **If auth fails, fix it automatically** — run `tempo wallet login` as appropriate, then retry.
- **Do not mix tools.** Use tempo for Tempo challenges.


path: references/gotchas.md
content: # Codex MPP Gotchas

Common failure points when using the MPP payment flow.

## Mutations and subscriptions are not supported

MPP only works for `query` operations. Sending a mutation or subscription returns `403`. Use API key auth for those.

## API key takes precedence

If an `Authorization` header with an API key is present, the server uses API key auth and skips the payment flow. Don't mix them.

## Challenges expire

A `WWW-Authenticate` challenge is single-use and short-lived. If you get `invalid-challenge` on retry, request a fresh challenge by repeating the initial request.

## Credential encoding

The credential in `Authorization: Payment <credential>` must be base64url-encoded, not standard base64. A `malformed-credential` error usually means wrong encoding or broken JSON.

## `tempo request` handles the flow automatically

If the user has the Tempo CLI installed, `tempo request` handles the full 402 challenge/payment/retry cycle in one command. Don't manually implement the flow when `tempo request` is available.

## Check wallet balance before making requests

Both `tempo wallet -t whoami` should be run before paid requests. An insufficient balance mid-flow produces confusing errors.


path: references/mpp-flow.md
content: # MPP Auth Flow Reference

## Auth matrix (MPP mode)

| Mode | Headers | Supports | Notes |
| ---- | ------- | -------- | ----- |
| MPP | `Authorization: Payment <credential>` | query only | `402` challenge/credential flow |

## Details

- Initial unpaid query returns `402` with multiple `WWW-Authenticate: Payment ...` challenges.
- Retry with `Authorization: Payment <credential>`.
- Success returns GraphQL data + `Payment-Receipt`.
- Mutation/subscription in MPP mode returns `403`.
- Valid API key/bearer auth takes precedence over the payment flow.

## Common failures

| Symptom | Likely cause | Fix |
| ------- | ------------ | --- |
| 402 + `WWW-Authenticate` | MPP challenge required | Solve one challenge and retry with `Authorization: Payment ...` |
| 402 + `malformed-credential` | Bad base64url or JSON credential | Rebuild credential payload |
| 402 + `invalid-challenge` | Unknown/expired/used challenge | Re-request and solve a fresh challenge |
| 402 + `verification-failed` | Payment proof rejected | Recreate proof for the returned challenge |
| 403 in MPP mode | Mutation or subscription attempt | Use API key/bearer auth for non-query operations |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)