Guides

Keys, balance & billing

One prepaid balance pays for every API. Each call has a fixed price, you are charged only when it succeeds, and every response tells you what it cost.

How money moves

1

Top up your balance

In Console → Billing, add funds by card or USDC. The minimum top-up is $1.

2

Create an API key

In Console → API Keys, create a key. It starts with pk- and is shown only once, so store it somewhere safe.

3

Call any API

Before forwarding, the gateway holds the call's price from your balance. If the upstream succeeds the hold becomes a charge; otherwise it is released and you pay nothing.

API keys

Send your key as Authorization: Bearer pk-… (or X-API-Key: pk-…). The same key works for every API, the AI gateway, MCP, the CLI and the SDKs. Create as many as you like, for example one per agent or environment, and set limits on each in Console → API Keys.

Per-key settings

LimitUSD

A spending cap for this key. Once reached, calls return 402 api key spend limit reached until you raise or reset it. Use it so one runaway agent loop can't drain your balance.

IP allowlistIP / CIDR

Up to 100 IPs or CIDR ranges (e.g. 203.0.113.7, 10.0.0.0/8). Requests from other addresses get 403 client IP not allowed for this API key. Empty means any IP.

Siteshostnames

Restricts the key to web pages on your domains, turning it into a browser key. See Browser keys.

Rotate

Issues a new key with the same settings and spend so far. The old key keeps working for a grace period (24 hours by default, up to 7 days) so you can swap it into agents and CI without downtime.

Revoke

Deleting a key stops it immediately; further calls get 401 invalid or revoked API key.

Never ship an unrestricted key in a web page or mobile app. Keep keys on your server, or use a browser key restricted to your sites.

Balance and top-up

Card: pay through Stripe Checkout; the balance updates as soon as the payment clears. You can also turn on auto-recharge to top up when the balance runs low.
USDC: send USDC (on Base by default) to the deposit address shown for your order. Each order has its own exact amount and stays valid for 24 hours, which is how the deposit is matched to your account.

Your balance is shown in the console header. Agents can read it, and the ledger behind it, with the same key:

bash

curl https://gw.pikeway.ai/v1/wallet/balance -H "Authorization: Bearer $PIKEWAY_KEY"
# {"balance":{"value":12.48,"currency":"USD"}, …}

curl https://gw.pikeway.ai/v1/wallet/activities -H "Authorization: Bearer $PIKEWAY_KEY"   # charges, refunds, top-ups

If the balance can't cover a call's price, the gateway returns 402 insufficient balance without calling the upstream.

Per-call pricing

Each endpoint has a fixed price in USD, set by the provider and shown on its marketplace page and by /v1/inspect. Nothing in your request changes it. AI models are the exception: they are billed by tokens, see AI gateway. WebSocket streams have their own connection, message and minute prices, see WebSocket.

Some APIs offer volume tiers: once your calls to that API in the current month pass a threshold, later calls get a discount, reported in X-Pikeway-Volume-Discount.

You only pay for successful calls

A call is charged only when the upstream returns a 2xx response. You are not charged when:

the upstream returns an error status (4xx, 5xx) or a redirect (3xx), or can't be reached (502);
the upstream answers 200 but its body reports a failure (APIs with business error codes, GraphQL responses with only errors, gRPC with a non-zero status). These carry X-Pikeway-Upstream-Error;
the gateway rejects the request first (bad key, missing parameters, rate limit, insufficient balance);
the charge can't be recorded. The gateway then returns 503 and does not deliver the response at all.

Read the cost from the response

Every gateway response carries X-Pikeway-Cost (USD charged for this call, 0 when nothing was charged) and X-Pikeway-Call-Id. Both are exposed to browsers via CORS.

bash

curl -i "https://gw.pikeway.ai/gw/dexscreener/latest/dex/search?q=WBTC" \
  -H "Authorization: Bearer $PIKEWAY_KEY"

# HTTP/1.1 200 OK
# X-Pikeway-Call-Id: 0192f3c1-…
# X-Pikeway-Cost: 0.0003

Billing headers

X-Pikeway-CostUSD

Amount charged for this call.

X-Pikeway-Call-Idstring

Unique id; matches your call log and is what you quote in a dispute.

X-Pikeway-Tokensin+out

AI calls: prompt and completion tokens billed.

X-Pikeway-Planstring

Name of the subscription plan that covered the call.

X-Pikeway-Quota-Remainingint

Included calls left in the current plan period.

X-Pikeway-Volume-Discount%

Volume discount applied to this call.

Safe retries with Idempotency-Key

For calls that must not run twice, send an Idempotency-Key. Within the same API key, a repeated key is never forwarded or charged again; the gateway answers 409 instead.

bash

curl -X POST "https://gw.pikeway.ai/gw/<slug>/<path>" \
  -H "Authorization: Bearer $PIKEWAY_KEY" \
  -H "Idempotency-Key: order-7f3a" \
  -d '{ … }'
# Retrying with the same Idempotency-Key never forwards or charges twice (409 on a duplicate).

Subscriptions

Some providers sell plans in addition to (or instead of) per-call pricing. Subscribe on the API's marketplace page and manage plans in Console → Subscriptions. While a plan is active:

calls within the included quota cost nothing, and only successful calls use up quota;
after the quota, the plan either blocks further calls (429 plan quota exhausted) or charges an overage price, depending on how the provider set it up;
the plan's own rate limit applies instead of the API's default.

APIs that are sold only by subscription return 403 to keys without an active plan.

Disputes

Charged for a call that didn't deliver what the API promised? Open a dispute in Console → Disputes within 14 days of the charge, with the call id (from X-Pikeway-Call-Id or your call log) and a short reason.

The provider's share of each charge stays on hold for the dispute window, and an open dispute keeps it there.
Pikeway reviews it and either refunds (fully or partly) to your balance or rejects it. The status shows as OPEN, REFUNDED or REJECTED.
Each charge can be disputed once.