Skip to main content

​
What Gecko is

Docs and endpoints are built for humans. Gecko is the API comprehension layer for agents — the layer that translates an API’s surface for agents. 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 guessing whether the agent is calling it right. gecko comprehends an API and prints the MCP URL + one-click add strings
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.
Today a builder reads the docs, hand-writes a client, and still can’t tell if the agent is calling the API correctly. Gecko removes that step. It ingests an API’s surface (OpenAPI today), turns it into question-shaped, first-call-correct agent tools, drives the access/auth handshake, and lets the agent call the real API directly for data.

​
Where Gecko sits — three verbs, three layers

There are three distinct jobs in the agentic economy. Gecko does exactly one.
LayerWhat it doesExamples
APIs get PAIDbilling / settlement railx402, payment rails
skills get DISTRIBUTEDmarketplace / discoveryskill marketplaces
APIs get USEDcomprehension / consumptionGecko
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.

​
Honest status

V1 — the comprehension path — is live end-to-end against one real, painful API (the TxODDS World Cup API, on Solana mainnet, 857 tests passing), with a $0 recorded mode that runs the whole path offline. Ingest is OpenAPI 3.x today. The multi-API correctness work is V2 and not yet live. Gecko does not claim to work on any API yet, and it does not verify or vouch for the data an API returns. See Status for the full picture.

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