What Gecko is
Docs and endpoints are built for humans. Gecko is where agents and APIs finally speak the same language — it translates any API into tools your agent calls right the first time. Point an agent at an API — even one behind human-shaped docs and a paywall — and it finds the right call, makes it correctly the first time, and runs. No client to hand-write, no key pasted into a config, no guessing whether the agent is calling it right. Three promises, one layer:- Right the first time — Gecko reads the API before your agent calls it. Right endpoint, right parameters, right auth.
- Keys stay hidden — your key lives on your machine and is used only at the moment of the call, sent only to the API’s own host. Never in a file, never inside the agent.
- Poison gets caught — a manipulated API (a doctored description, a poisoned example) is screened and quarantined before your agent ever sees it.
The brand is Gecko. The PyPI package is
gecko-surf (pip install gecko-surf),
the import is gecko (from gecko import …), and the CLI is gecko.Where Gecko sits — three verbs, three layers
There are three distinct jobs in the agentic economy. Gecko does exactly one.
Gecko composes on top of x402 / MCP / payment catalogs — it consumes them as
input. It is not a payment rail and not a marketplace. It is the layer that
makes an API actually usable by an agent.
What it does, in one path
1
Ingest the surface
Parse an OpenAPI 3.x document into normalized operations and parameters — the
surface only (method, path, params, schemas). Never the response data.
2
Catalog
Build a capability list so an agent can go from natural-language intent to the
right endpoint. Lexical at this scale; no vectors.
3
Comprehend
Turn each operation into a question-shaped tool an agent picks correctly with no
API docs in front of it. Auth headers are hidden from the agent.
4
Access
Drive the access/subscription handshake. The whole engine/adapter seam is one
function:
Session.auth_headers().5
Call
The agent calls the real API directly; Gecko injects credentials and stays out
of the data path.
Control plane, never data plane
Gecko holds the API’s surface, the generated tool defs, and correctness metadata. It never stores response payloads, user data, or secrets. That invariant is what lets it ingest an API’s surface unilaterally — and it is a hard boundary, not a setting.What’s live
Comprehension is live end-to-end on Solana mainnet against a real paywalled API (the TxODDS World Cup API, 857 tests passing), and the same engine is proven keyless at scale: Stripe — 587 tools, 99.8% first-call-correct · Twilio — 100% · Jupiter — 100% — with a$0 recorded mode that runs the whole path offline. Ingest is OpenAPI 3.x, or a spec
recovered from a docs page. See Status for what’s next.
Next
Quickstart
Run the $0 recorded demo — goal to correct call to data, no keys, no spend.
Concepts
The vocabulary: surface, operation, question-shaped tool, session, modes.
How comprehension works
Ingest, catalog, and the question-shaped tool generator, tied to the real code.
For AI agents
The MCP surface an agent installs, and how Gecko makes an API discoverable.