> ## 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
> Your agent's first try is the real one. Gecko puts a rehearsal in between. It runs the call somewhere that doesn't count, shows you what will happen, and only then lets it count.
**Today, an agent's first attempt at your API is already the real one.**
And when it goes wrong it usually goes wrong quietly: the call is well-formed, the API
accepts it, nothing errors, and the world is now wrong.
**Gecko puts a rehearsal in between.** It works out which call to make, fills in what the
documentation cannot carry, runs it somewhere that doesn't count, and hands back a
**receipt** of what will happen. Then, and only then, it counts.
On 2026-08-06 an agent bought a bottle of water for 10 cents on Solana mainnet. **Before
paying, Gecko said exactly what the transaction would do, and that is exactly what
happened.** The engine repo's ledger (`docs/mainnet-ledger.jsonl`) now holds 50 landed
mainnet transactions (2026-09-01), across two storefronts, an Orca Whirlpool pool and
several account states. Every row that records both a prediction and a charge matches to
the compute unit. The latest three were prepared by the hosted MCP and signed headless by
a hosted signer, with no key on the machine that planned them. [See the
signatures](/mainnet); they are public, so you can check rather than trust us.
*For the technically minded: each receipt predicted the exact compute units the chain
then charged (36,508, then 36,399, then 22,527 for a different store), matching to the
unit, because the simulation runs the identical execution against the state it will land
on, not an approximation of it.*
```bash theme={null}
npx @geckovision/gecko prove "" # the rehearsal: which call, and will it work
npx @geckovision/gecko add # comprehend any API, $0, no live call
npx @geckovision/gecko watch # keep it true: re-run it as CI
npx @geckovision/gecko serve # your agent uses it over MCP
```
No install at all? Wire the hosted surface: the runbook is
[`agents.md`](https://www.geckovision.tech/agents.md), every client's config is
[`mcp-config.json`](https://www.geckovision.tech/mcp-config.json), and
`npx skills add GeckoVision/gecko-surf` installs the seven skills, `gecko-setup` first.
The brand is **Gecko**. The CLI is **`gecko`**. Install it with
`npm install -g @geckovision/gecko` (prebuilt binary, no Python) or from PyPI as
**`gecko-surf`** (`pip install gecko-surf` / `uv tool install gecko-surf`). The import is
**`gecko`** (`from gecko import …`).
## Why a description isn't enough
A specification tells you what a call **looks like**. It cannot tell you whether it will
**work**. That is structural, not a quality defect. It is just as true of a perfect spec:
* **Nothing in a spec runs.** `/v1/assets/{symbol}/state` is schema-correct with
`symbol` = `"string"`. Live, that call is a 404. Only running it tells you.
* **Some facts can't be in a spec.** Jupiter's route surface declares **9 accounts**; the
instruction that lands carries **25**. The other 16 are legs of a route computed a
second ago, facts about a different surface.
* **A spec can't declare a join to a spec it's never heard of.** The mint that connects
three Solana APIs is named differently in each and declared by none.
* **A spec is a snapshot.** Nothing in it says when it stopped being true.
Gecko replaces the guess with a rehearsal. The full answer to *"I already have an OpenAPI
spec and an MCP server"*, with the measured numbers, is in
[Gecko 101](/gecko-101#what-a-specification-cannot-tell-you).
Every fact is tagged `extracted` from the surface, `recovered` from source, or
honestly `flagged` as unknown. Never fabricated. Below the retrieval floor, Gecko
says "no start found" instead of inventing one.
An action is simulated first, producing a **Receipt**: pass, or a categorical
revert class, plus a binding over the exact bytes, before any spend. See
[The Receipt](/receipt).
Outcomes land in a categorical corpus; an N-confirmed drift series flags when a
provider ships a change that breaks a working call. See [Stay correct](/stay-correct).
Keys are injected at call time from your OS keychain. The model never sees a
credential, and no key goes in `mcp.json`. See [Access & auth](/access-and-auth).
## Who this is for
Not "teams with bad APIs." The gap above is in every spec. What changes is what a wrong
call costs you:
* **The call spends or commits something.** There is no retry loop when the first attempt
is the real one.
* **The agent runs unattended.** Nobody reads the diff before it happens.
* **You are on your Nth surface.** The cost is per-API and it compounds.
One API, and a human reviewing every diff? The value is real but it is smaller than the
cost of adopting anything, a one-week job either way. That is an honest no. Gecko earns
its place where a wrong call costs something.
## Proof, not promises
Live, on a **surfpool mainnet fork** (a mainnet-backed state snapshot, **not mainnet**),
simulation only, \$0, nothing signed or broadcast:
| Case | Naive path | Gecko |
| - | - | - |
| Pump.fun buy | ❌ reverts, `AccountNotInitialized (3012)` | ✅ lands, 86,669 CU |
| Meteora DLMM swap | ❌ reverts, derive-only, no ATA/wrap/bin-array preludes | ✅ wrap → swap → unwrap, 81,964 CU |
| Meteora pool derivation | ❌ stale 3-seed scheme → the wrong pool, silently | ✅ correct 4-seed derivation, differential-proven |
| Docs-only API (no spec) | agent invents endpoints | ✅ draft spec recovered, claims marked `VERIFIED` / `REFUTED` |
The facts behind those passes are not on any surface: a 4th PDA seed the SDK added in
2024, an account the IDL only mentions in prose, a fee field resolved by a refuting
simulation. That is the graph your agent traverses.
Compute-unit numbers are **measured per run** against a fork snapshot and vary slightly
with on-chain state. The stable claim is the side-by-side verdict: the naive path's
revert class vs Gecko's pass. The `base_factor` row is a **derivation** result. It has
no CU number and is never paired with one.
## Where Gecko sits
Gecko is **not the agent** and **not an orchestrator**. It is the memory-and-context
substrate *under* other people's agents: it comprehends external surfaces, projects them
as first-call-correct tools over MCP, verifies actions by simulation before execution,
and **never signs, never holds a key, never stores payloads**. The one thing it sends to
a chain is signed bytes that verify against a binding it issued.
There are three distinct jobs in the agentic economy. Gecko does exactly one.
| Layer | What it does |
| - | - |
| APIs get **PAID** | billing / settlement rail |
| skills get **DISTRIBUTED** | marketplace / discovery |
| **APIs get USED** | **comprehension, verification, memory**: Gecko |
Gecko **composes on top of** MCP, x402, and payment catalogs. It *consumes* them as
input. It is not a payment rail and not a marketplace. Building transactions belongs to
builders; signing belongs to signers. That is the design, not a gap.
## 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 a surface unilaterally, and it is a hard boundary, not a setting.
## Next
doctor → add → report → serve. The \$0 recorded path: no key, no spend.
The three views, with the interactive diagrams.
What a Receipt asserts, what the binding covers, and in detail what it does not.
Intent → the right starting point, with a provenance-tagged derive plan.
Surface, provenance, receipt, drift, question-shaped tool, the two modes.
What works today, and what is honestly not built yet.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.