Skip to main content

​
Gateway Skill

The Apiosk gateway skill is an installable skill for coding agents — Claude Code, Codex, and other shell-capable agents — that need to run paid gateway requests without wiring up an MCP server. The skill teaches the agent the gateway’s HTTP contract: discover an API, preflight for free, make a paid call, and read the receipt headers. The agent never holds funds or signs payments. A buyer connects a budget once and mints a connect token; the gateway settles each call on the buyer’s behalf over USDC (x402 on Base) or SEPA.

​
Install

npx skills add Apiosk/openclaw-apiosk --skill apiosk-gateway
A starter kit with a runnable example lives at github.com/Apiosk/apiosk-x402-starter.

​
Setup (one time)

  1. The buyer creates a connection and mints a connect token at buyer.apiosk.com. It binds a budget, wallet(s), and/or a SEPA mandate.
  2. Provide the token to the skill through the APIOSK_CONNECT_TOKEN environment variable.
  3. The endpoints are fixed — no other config is needed:
    • Gateway: https://gateway.apiosk.com
    • MCP: https://mcp.apiosk.com/mcp
The connect token is a production credential. Never print it, echo it in tool output, commit it, or include it in a summary. Read it from the environment.
Every request authenticates with one header (pick one and keep it consistent): 
X-Apiosk-Connect-Token: $APIOSK_CONNECT_TOKEN
# or
Authorization: Bearer $APIOSK_CONNECT_TOKEN

​
The core loop

self-check → discover → preflight → call (with idempotency key) → log the receipt. Apiosk handles rail selection, settlement, retries, and the bank.

​
1. Self-check — budget and rails

curl -s https://gateway.apiosk.com/v1/me \
  -H "X-Apiosk-Connect-Token: $APIOSK_CONNECT_TOKEN"
Returns the authorized rails, wallet caps with spent_today, and SEPA caps.

​
2. Discover APIs

curl -s "https://gateway.apiosk.com/v1/apis?search=weather&limit=20" \
  -H "X-Apiosk-Connect-Token: $APIOSK_CONNECT_TOKEN"

# Inspect one API: operations, per-operation price, input/output schema
curl -s https://gateway.apiosk.com/v1/apis/weather \
  -H "X-Apiosk-Connect-Token: $APIOSK_CONNECT_TOKEN"
Budget from operations[i].price_usd, not the top-level price_usd — multi-endpoint APIs differ per operation.

​
3. Preflight (free dry-run)

curl -s "https://gateway.apiosk.com/weather/current?city=Amsterdam" \
  -H "X-Apiosk-Connect-Token: $APIOSK_CONNECT_TOKEN" \
  -H "X-Apiosk-Dry-Run: 1"
Read would_succeed and reason_if_not. Preflight never touches the chain or increments counters. Always preflight calls above $0.10 or batches of more than five calls to the same slug.

​
4. Make the paid call

curl -s "https://gateway.apiosk.com/weather/current?city=Amsterdam" \
  -H "X-Apiosk-Connect-Token: $APIOSK_CONNECT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" -D -
Use a fresh UUID per logical call. Reuse the same key only to safely retry a 5xx or timeout — a replay returns the cached result with no second charge.

​
5. Log the receipt

Every paid response carries receipt headers. Trust the headers, not your prediction of the price.
HeaderMeaning
X-Apiosk-Payment-Railx402, sepa, or credits
X-Apiosk-Price-ListedAuthorized price (USDC, gross) — log this to trace spend
X-Apiosk-Tx-HashBase transaction hash (USDC only)
X-Apiosk-Idempotent-Replaytrue means a cached replay, no new charge

​
Golden rules

  • Self-check before paid work; preflight anything non-trivial.
  • One fresh Idempotency-Key per logical call.
  • Never probe with real calls to learn a price — use /v1/apis/{slug} plus preflight.
  • Never try to choose the rail or sign payments — the gateway does both.
  • Never expose APIOSK_CONNECT_TOKEN anywhere user-visible.

​
MCP instead of raw HTTP

If your runtime speaks MCP, point it at https://mcp.apiosk.com/mcp with the same connect-token header. Same rails, same settlement, same receipts. See /guides/mcp-clients.