Gateway

Call an API

Proxy a request to any API in the marketplace. Pikeway authenticates you, injects the provider's credentials, forwards the request and charges the endpoint's price only if the call succeeds.

ANY/gw/{slug}/{path}

Everything after /gw/{slug} (path, query string, method, body and most headers) is forwarded to the provider's base URL. Use the exact path shown on the API's marketplace page; /v1/inspect returns it too.

Authentication

Send your key as Authorization: Bearer pk-… (or X-API-Key).

Parameters

Path

slugstringrequired

The API's slug, e.g. birdeye or coingecko (shown on its marketplace page).

pathstring

The upstream path, forwarded as-is. Percent-encoded characters such as %2F are kept encoded.

Query and body

…any

Whatever the upstream endpoint expects. Query parameters marked required on the endpoint are checked first: if any is empty you get 400 with a missing list, before anything is forwarded or charged.

Headers

AuthorizationBearer pk-…

Your Pikeway key. Removed before forwarding.

Idempotency-Keystring ≤ 255

Optional. The gateway forwards and charges a given key at most once; a repeat returns 409. Also lets POST/PATCH requests fail over to a backup upstream when the provider marked them retry-safe.

Other request headers go to the upstream, except Cookie, Origin, Referer, X-Forwarded-*, sec-fetch-* / sec-ch-* and Accept-Encoding.

Request

bash

curl "https://gw.pikeway.ai/gw/birdeye/defi/price?address=So11111111111111111111111111111111111111112" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" -i

POST, PUT, PATCH and DELETE work the same way; send the body the upstream expects:

bash

curl -X POST "https://gw.pikeway.ai/gw/{slug}/{path}" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7781" \
  -d '{"...": "..."}'

Response

The provider's status code, headers and body come back unchanged, plus Pikeway's headers. Server-sent events and large bodies are streamed through when the API has no response rules or caching.

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
X-Pikeway-Call-Id: 0192f6a1-3c1e-7b5a-9d2e-5c4f1a7e8b90
X-Pikeway-Cost: 0.001

{
  "success": true,
  "data": { "value": 172.41, "updateUnixTime": 1761297120 }
}

Pikeway response headers

X-Pikeway-Call-Idstring

Call id (also the runId for GET /v1/runs/{id}). Set on success and on upstream failures.

X-Pikeway-CostUSD

Amount charged. 0 when not billed (non-2xx, business-code failure, plan quota, your own key).

X-Pikeway-CacheHIT | MISS

When the provider enabled response caching (GET only). Hits are billed at the normal price.

X-Pikeway-Plan · X-Pikeway-Quota-Remainingstring · int

When the call used your subscription plan.

X-Pikeway-Volume-Discountpercent

Volume-tier discount applied to this call.

X-Pikeway-Upstream-Errorstring

business-code, graphql-errors or grpc-status-N when a 2xx was judged a failure (not billed).

X-Pikeway-Upstream-Attemptsint

How many upstream targets were tried when the gateway failed over.

X-Pikeway-Byok1

Ran on your own provider key; not charged.

What happens on each call

Resolve the API by slug and authenticate the key (revoked, IP and origin restrictions).
Apply rate limits: per-second spike arrest, then the API's per-key limit (or your plan's per-minute limit).
Match the endpoint by method and path to get its price; apply plan quota, volume discounts or your own provider key.
Validate: required query parameters, and the request schema if the provider turned validation on.
Check balance and the key's spend limit, then hold the price on your balance.
Forward to the provider (failing over to backup upstreams for retry-safe requests) and judge success.
Charge the hold on success, release it otherwise, then return the response.

Errors

400 missing required query parameters (with missing), schema validation failure.
401 missing or invalid key. 402 insufficient balance or key spend limit reached.
403 key restriction, subscription required, paused key/account, missing own provider key. 404 unknown or private API.
409 Idempotency-Key reused. 429 rate limits and plan quota (see Retry-After).
502 upstream unreachable (not charged). 503 billing unavailable or API paused (not charged).

Full list in Errors.

Free mock responses

ANY/mock/{slug}/{path}

Same path as /gw, but returns the endpoint's example response instead of calling the provider. No key, no charge, never touches the upstream. Useful for wiring up parsing code before you pay. Limited to 30 requests per minute per IP.

bash

curl -i "https://gw.pikeway.ai/mock/birdeye/defi/price?address=So11111111111111111111111111111111111111112"

The body is the endpoint's first 2xx example: a published example, else an examples[*].value, else a sample generated from the response schema. Responses carry X-Pikeway-Mock: true and X-Pikeway-Cost: 0.

404 no endpoint matches GET /… no endpoint with that method and path.
404 no example response yet for this endpoint … the provider hasn't published an example (auto examples appear after the first successful live call, if enabled).
429 mock rate limit exceeded (30/min)

WebSocket

APIs with WebSocket endpoints are proxied at /ws/{slug}/{path}. A key is required (header, or ?key=pk-… from browsers); billing is per connection, message or minute. See the WebSocket guide.

Don't know the slug or path? Use /v1/discover and /v1/inspect, or let /v1/run build the request from structured input.