Delegation API reference

The Gatewayz delegation API is a small REST API at https://api.gatewayz.ai that lets a person or an AI agent check the yield-as-inference program, link a Cardano stake address with a CIP-8 signature, record eligibility, read the 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>.

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.

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.

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

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

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.

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 signData; the 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.

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.

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.

POST /v1/chat/completions

OpenAI-compatible inference. Billed at 1% of list price while the discount balance lasts; the other 99% is drawn from the balance.

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.

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.

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

Where are the OpenAPI spec and interactive docs?

The machine-readable OpenAPI description is at https://api.gatewayz.ai/openapi.json, and interactive docs are at 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, as of 2026-10-27
• CIP-0030: Cardano dApp-Wallet Web Bridge, as of 2026-10-27