# Genesis402 auth.md

Audience: AI agents and programs calling the pay-per-call endpoints on https://twin.unykorn.org.

## Registration
There is no account and no registration, and there is no OAuth on this service. No API key or client id is issued.

## Credentials
A paid call is authorized in one of two ways.

### 1. Pay per call
- A request without payment gets `402 Payment Required` with a `PAYMENT-REQUIRED` header (x402 v2) and, where offered, an MPP `WWW-Authenticate` challenge.
- Resend the same request with the signed payment in the `PAYMENT-SIGNATURE` header (x402) or `Authorization: Payment` (MPP).
- One payment authorizes exactly one execution of that request. It cannot be reused.

### 2. Prepaid credit (optional)
- Provisioning: a paid call to https://twin.unykorn.org/credits/5 or https://twin.unykorn.org/credits/25 returns a bearer token (`g402c_…`, shown once) holding that balance in US dollars.
- Use: send it as `X-Genesis402-Credit: <token>` on a paid endpoint. The call runs at its listed price, drawn from the balance.
- Balance and history: https://twin.unykorn.org/credits/balance and https://twin.unykorn.org/credits/history, with the same header.
- Routes sold by a desk agent to its own wallet do not accept credits; they take x402 or MPP only.
- Keep the token secret: whoever holds it can spend the balance.

## Optional agent identity
Send `X-AGENT-ID: <ERC-8004 agent id>` to have your agent named on the receipt. It is marked verified only when the paying wallet owns that agent or is its registered agent wallet. It grants no access by itself.

## Where to start
- Terms, prices and accepted payment options: https://twin.unykorn.org/.well-known/x402
- Skill for agents: https://twin.unykorn.org/.well-known/agent-skills/genesis402-pay-per-call/SKILL.md