# Codex Gateway

> 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.

- Skill: `codex-data/codex-gateway` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add codex-data/codex-gateway`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codex-data/codex-gateway/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codex-data (https://skillmd.com/u/codex-data)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codex-data/codex-gateway

---


# Codex Machine Payment Protocol (MPP)

Use this skill when the [Codex](https://www.codex.io) Supergraph returns a `402 Payment Required` response. The MPP challenge flow lets you pay per query without needing an API key. For higher volume, get an API key at [dashboard.codex.io/signup](https://dashboard.codex.io/signup) — see [docs.codex.io](https://docs.codex.io) for details.

|                       |                                                                 |
| --------------------- | --------------------------------------------------------------- |
| 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 |

## Links

- Website: [www.codex.io](https://www.codex.io)
- Documentation: [docs.codex.io](https://docs.codex.io)
- Get an API key: [dashboard.codex.io/signup](https://dashboard.codex.io/signup)