> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geckovision.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Where agents and APIs finally speak the same language — point Gecko at any API and your agent calls it right the first time.
## 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`**.
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* (an OpenAPI spec, or one recovered from a docs page), 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.
| Layer | What it does | Examples |
| -------------------------- | ------------------------------- | ------------------- |
| APIs get **PAID** | billing / settlement rail | x402, payment rails |
| skills get **DISTRIBUTED** | marketplace / discovery | skill marketplaces |
| **APIs get USED** | **comprehension / consumption** | **Gecko** |
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
Parse an OpenAPI 3.x document into normalized operations and parameters — the
*surface only* (method, path, params, schemas). Never the response data.
Build a capability list so an agent can go from natural-language intent to the
right endpoint. Lexical at this scale; no vectors.
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.
Drive the access/subscription handshake. The whole engine/adapter seam is one
function: `Session.auth_headers()`.
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](/status) for what's next.
## Next
Run the \$0 recorded demo — goal to correct call to data, no keys, no spend.
The vocabulary: surface, operation, question-shaped tool, session, modes.
Ingest, catalog, and the question-shaped tool generator, tied to the real code.
The MCP surface an agent installs, and how Gecko makes an API discoverable.