# Delegation API reference

> The Gatewayz delegation API lives at https://api.gatewayz.ai. GET /delegation/status needs no auth; the nonce, link, eligibility and rewards endpoints and the /v1/chat/completions and /v1/messages inference endpoints take Authorization: Bearer with a Gatewayz API key. The yield offer, quote and policy endpoints and an MCP server are planned, not live.

**In one line:** Seven live endpoints cover status, wallet linking, eligibility, balance and inference; the yield endpoints are planned.

The Gatewayz delegation API is a small REST API at `https://api.gatewayz.ai` that lets a person or an [AI agent](/learn/what-is-an-ai-agent) check the yield-as-inference program, link a Cardano [stake address](/yield/glossary#stake-address) with a [CIP-8](/yield/glossary#cip-8) signature, record eligibility, read the [inference discount balance](/yield/glossary#inference-discount-balance) and spend it on inference. Seven endpoints are live today; the yield offer, quote and policy endpoints and an MCP server are planned. Every authenticated call uses `Authorization: Bearer <Gatewayz API key>`.

**Pre-launch.** The program is built and switched off on mainnet. A working demo runs on Cardano's preprod testnet with test ADA, by invitation. Not available to US or Canadian persons. Every participant must confirm they are not a US or Canadian person before linking a wallet.

## Key takeaways

- Base URL: `https://api.gatewayz.ai`. The OpenAPI description is at `https://api.gatewayz.ai/openapi.json` and interactive docs at `https://api.gatewayz.ai/docs`.
- `GET /delegation/status` is the only unauthenticated endpoint; everything else needs your Gatewayz [API key](/yield/glossary#api-key).
- Wallet linking is two calls, nonce then link, around one local CIP-8 signature. No transaction is involved.
- Only key-hash stake addresses (`stake1u...`) are supported; script stake addresses (`stake17...`) are rejected.
- Errors return an HTTP status, a stable `code` and a `remedy`; see [Errors](/yield/agents/errors).
- `/v1/yield/offer`, `/v1/yield/quote`, `/v1/yield/policy` and the MCP server are planned and do not respond today.

## Which endpoints are live?

These seven endpoints are live. The descriptions come from the same file that generates `/yield/offer.json`, so this table and the machine-readable offer always match.

| Method | Path | Auth | Status | What it does |
| --- | --- | --- | --- | --- |
| GET | `/delegation/status` | none | live | Whether the program is on, the Cardano pool id and network, the reward share, the discount and the disclaimer. |
| POST | `/auth/wallet/cardano/nonce` | API key | live | Body {stake_address, not_us_ca_person}. Returns {nonce, message, expires_at}: the message your wallet signs (CIP-8). |
| POST | `/auth/wallet/cardano/link` | API key | live | Body {stake_address, signature, key, not_us_ca_person}: the COSE_Sign1 and COSE_Key hex from your wallet. Links the stake address to the account that owns the API key. |
| POST | `/delegation/eligibility` | API key | live | Body {not_us_ca_person: true}. Records the not-US/CA attestation required before any discount is granted. |
| GET | `/delegation/rewards` | API key | live | Linked wallets, measured positions, the discount balance and history, eligibility and the disclaimer. |
| POST | `/v1/chat/completions` | API key | live | OpenAI-compatible inference. Billed at 1% of list price while the discount balance lasts. |
| POST | `/v1/messages` | API key | live | Anthropic Messages-compatible inference, billed the same way. |

## How do you authenticate?

Send your Gatewayz API key as a bearer token on every call except `GET /delegation/status`. The key identifies the account: a wallet you link is linked to the account that owns the key, and the discount is spent by requests made with keys on that account.

```bash
-H "Authorization: Bearer $GATEWAYZ_API_KEY"
```

Keep the key out of source control and logs; anyone holding it can spend the discount. [API endpoints and API keys explained](/learn/api-endpoint-api-key-explained) covers the basics.

## What does each live endpoint do?

Each section below lists the request, the response fields and a `curl` example. Field descriptions follow the published offer; for exact JSON types, read the OpenAPI description.

### GET /delegation/status

Reports whether the program is on, the Cardano pool id and network, the reward share, the discount and the disclaimer. No authentication.

- **Request:** no body.
- **Response:** program state, the Cardano pool id and network (the pool id is at `data.cardano.pool_id`), the reward share, the discount and the disclaimer text.

```bash
curl -s https://api.gatewayz.ai/delegation/status
```

Call it before delegating, and treat a missing pool id as "not live on this network yet".

### POST /auth/wallet/cardano/nonce

Issues a one-time message for your stake key to sign.

- **Request:** `stake_address` (bech32, `stake1u...`), `not_us_ca_person` (boolean, your attestation that you are not a US or Canadian person).
- **Response:** `nonce` (the one-time value), `message` (the exact text to sign with CIP-8), `expires_at` (when the nonce stops being accepted).

```bash
curl -s -X POST https://api.gatewayz.ai/auth/wallet/cardano/nonce \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stake_address": "stake1u...", "not_us_ca_person": true}'
```

### POST /auth/wallet/cardano/link

Verifies the CIP-8 signature and links the stake address to the account that owns the API key.

- **Request:** `stake_address`; `signature` (the COSE_Sign1 your wallet produced, hex); `key` (the COSE_Key your wallet produced, hex); `not_us_ca_person`.
- **Response:** confirmation that the stake address is linked to your account. Failures carry a typed error such as `invalid_signature`, `payload_mismatch` or `wallet_linked_to_other_account`.

```bash
curl -s -X POST https://api.gatewayz.ai/auth/wallet/cardano/link \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stake_address": "stake1u...", "signature": "84...", "key": "a4...", "not_us_ca_person": true}'
```

A browser wallet produces `signature` and `key` from [CIP-30](/yield/glossary#cip-30) `signData`; the [quickstart](/yield/agents/quickstart) shows the call and the hex encoding it needs.

### POST /delegation/eligibility

Records the not-US/CA attestation required before any discount is granted. Use it if you did not send `not_us_ca_person: true` with the nonce or link call.

- **Request:** `{"not_us_ca_person": true}`.
- **Response:** confirmation that the attestation is recorded. A `503 eligibility_unavailable` means it could not be stored; retry later.

```bash
curl -s -X POST https://api.gatewayz.ai/delegation/eligibility \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"not_us_ca_person": true}'
```

### GET /delegation/rewards

Reports everything about your participation: linked wallets, measured positions, the discount balance and history, eligibility and the disclaimer.

- **Request:** no body.
- **Response:** linked wallets; measured positions (your stake as measured for each epoch); the discount balance; the history of credited discounts, recorded in USD at the ADA price when each epoch was recorded; your eligibility; the disclaimer.

```bash
curl -s https://api.gatewayz.ai/delegation/rewards \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY"
```

The history is what you compare with the output of the [verify script](/yield/verify).

### POST /v1/chat/completions

OpenAI-compatible inference. Billed at 1% of [list price](/yield/glossary#list-price) while the discount balance lasts; the other 99% is drawn from the balance.

```bash
curl -s https://api.gatewayz.ai/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model id>", "messages": [{"role": "user", "content": "Hello"}]}'
```

### POST /v1/messages

Anthropic Messages-compatible inference, billed the same way.

```bash
curl -s https://api.gatewayz.ai/v1/messages \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model id>", "max_tokens": 256, "messages": [{"role": "user", "content": "Hello"}]}'
```

If the 1% you pay, or a request after the balance runs out, exceeds your credits, the call fails with `402 insufficient_credits`.

## Which endpoints are planned?

Three yield endpoints and an MCP server are planned. They do not respond today, and each row says what to use instead.

| Method | Path | Auth | Status | What it does |
| --- | --- | --- | --- | --- |
| GET | `/v1/yield/offer` | none | planned | This offer as JSON from the API. Today, read https://www.gatewayz.ai/yield/offer.json. |
| POST | `/v1/yield/quote` | none | planned | A server-side quote. Today, apply the formula in offer.json quote. |
| GET | `/v1/yield/policy` | API key | planned | Owner limits for agents: allowed assets, maximum stake, approval threshold. |

MCP server: planned. Tools: `yield_get_offer`, `yield_quote`, `yield_get_policy`, `yield_get_position`, `credits_balance`.

Until `/v1/yield/quote` ships, apply `quote.formula` from `https://www.gatewayz.ai/yield/offer.json` yourself; it is the same formula the [calculator](/yield/calculator) uses.

## Where are the OpenAPI spec and interactive docs?

The machine-readable OpenAPI description is at [https://api.gatewayz.ai/openapi.json](https://api.gatewayz.ai/openapi.json), and interactive docs are at [https://api.gatewayz.ai/docs](https://api.gatewayz.ai/docs). Use them for exact field types; use this page and `offer.json` for what each endpoint means for the program.

## Frequently asked questions

### Which Gatewayz delegation endpoint needs no API key?

Only `GET /delegation/status`. It reports whether the program is on, the Cardano pool id and network, the reward share, the discount and the disclaimer, so anyone can check the program before creating an account.

### What do the signature and key fields contain?

`signature` is the COSE_Sign1 structure and `key` is the COSE_Key structure that a Cardano wallet produces from a CIP-8 message signature, both hex-encoded. In a browser wallet they are the two fields CIP-30 `signData` gives back.

### Is there an endpoint that quotes my discount?

Not yet. `POST /v1/yield/quote` is planned. Today, read the `quote` object in `/yield/offer.json` and apply its formula, which is the same one the calculator uses.

### Does the discount change which model serves my request?

No. The discount only changes what a request costs. Rewards never influence routing, so `/v1/chat/completions` and `/v1/messages` behave exactly as they do without a discount.

### Where do I see my discount balance?

`GET /delegation/rewards` with your API key shows the balance, its history, your linked wallets, measured positions and eligibility.

## Sources

- [CIP-0008: Message Signing](https://cips.cardano.org/cip/CIP-0008), as of 2026-10-27
- [CIP-0030: Cardano dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-0030), as of 2026-10-27

## Related

- [A compute budget that refills itself](https://www.gatewayz.ai/yield/agents)
- [Quickstart: link a Cardano stake address with CIP-8](https://www.gatewayz.ai/yield/agents/quickstart)
- [Wallet link and delegation error codes](https://www.gatewayz.ai/yield/agents/errors)
- [Verify your discount from public chain data](https://www.gatewayz.ai/yield/verify)

---

Discounts are a share of staking rewards Gatewayz actually received, can change at any time, and are not a guaranteed return. Not available to US or Canadian persons. Every participant must confirm they are not a US or Canadian person before linking a wallet. Not investment, legal or tax advice. Figures as of 2026-10-27.

Updated 2026-10-27. Canonical page: https://www.gatewayz.ai/yield/agents/api