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

# Gecko 101

> Your agent tries the call before it makes it. One URL, no install, no key, and a receipt before anything is signed.

## The problem

Your agent's first call is the real one. There is no rehearsal.

A wrong call that errors is the cheap failure. You find out.

The expensive one is quiet. Well-formed, accepted, nothing throws, and the world is now
wrong. Nobody gets an alert for a call that worked and was wrong.

## Watch it run

Ten questions, four programs, one landed transaction. Every command real, one take.

<video autoPlay muted loop playsInline controls className="w-full aspect-video rounded-xl" src="https://mintcdn.com/gecko-d0bce12a/-uR_A6N66TKVZQ4z/assets/gecko-101.mp4?fit=max&auto=format&n=-uR_A6N66TKVZQ4z&q=85&s=00ffee1883237ce6000db12428b12ffe" data-path="assets/gecko-101.mp4" />

## What Gecko is

Gecko reads an API (its spec, its docs, or for a Solana program its IDL and source) and
turns it into tools your agent calls correctly the first time, every fact tagged with
where it came from.

For anything that costs money, it runs the call somewhere that doesn't count first and
hands back a **receipt** with a binding to the exact bytes. Then someone else signs.

<Note>
  Gecko is not the agent. It holds no key and signs nothing. The only thing it sends to a
  chain is signed bytes that verify against a binding it issued.
</Note>

## Your first call

No install, no account, no key, no spend. The flagship surface covers Solana storefronts,
Orca Whirlpool swaps, `find_start` and program graphs:

```bash theme={null}
claude mcp add --transport http gecko https://mcp.geckovision.tech/orquestra/mcp
```

Every other client's wiring is in
[`mcp-config.json`](https://www.geckovision.tech/mcp-config.json), and the executable
runbook is [`agents.md`](https://www.geckovision.tech/agents.md). Or let a skill do it:

```bash theme={null}
npx skills add GeckoVision/gecko-surf     # gecko-setup + six more
```

For a keyless HTTP API, same shape:

```bash theme={null}
claude mcp add --transport http pegana https://mcp.geckovision.tech/pegana/mcp
```

Ask, in plain words:

```
Is USDC still pegged right now?
```

```
USDC   PEGGED   $0.9998   confidence: high
```

Live answer, real production API. Your agent picked the right tool out of 28 and filled
the parameter, first try.

<Note>
  **Another client?** Put the same URL in your `mcp.json` under `mcpServers`. If it only
  speaks SSE, use `/pegana/sse`: same tools, older transport.
</Note>

The host serves ten surfaces. They are listed at
[`/.well-known/gecko.json`](https://mcp.geckovision.tech/.well-known/gecko.json) and
described at [`catalog.md`](https://www.geckovision.tech/catalog.md). The host root,
`/mcp`, serves two tools: `comprehend_api` (point it at your own API) and
`list_surfaces`.

## "I already have an OpenAPI spec and an MCP server"

Good. Keep both. Gecko reads the spec and speaks MCP.

**A specification tells you what a call looks like. It cannot tell you whether it will
work.** That is structural, and just as true of a perfect spec as a bad one.

| a spec cannot tell you | what that costs |
| - | - |
| **that the endpoint still answers** | a documented endpoint we were served returns 404. It was never real. |
| **facts that aren't about your API** | Jupiter's route surface declares 9 accounts. The call carries 25. The other 16 belong to a route chosen a second ago. |
| **a join to a spec it never heard of** | "is it pegged, and what can I exit at" spans three APIs. None declares the mint that connects them. |
| **how to be an interface** | 113,072 bytes of surface competing with your task, every turn. Gecko projects 23,382: 79.3% less, correctness held. |
| **a dry run** | neither a spec nor an MCP server has one. |
| **when it stopped being true** | a spec is a snapshot with no expiry. |

And one thing an MCP server *does*: it leaves your key in `mcp.json` or `.env`, inside the
agent's context. Gecko keeps it in your OS keychain and injects it at call time. The model
never sees it.

## The model underneath

<Steps>
  <Step title="Comprehend">
    Read the surface. Tag every fact `extracted`, `recovered`, or `flagged` as genuinely
    unknown. Never invented. Below the retrieval floor it says "no start found" instead
    of guessing.
  </Step>

  <Step title="Plan">
    Turn an intent into one specific call, including the accounts the surface does not
    carry. Solana programs derive addresses from seeds; those recipes are often missing
    from the IDL, and a guess gives you a valid-looking address for the wrong thing.
  </Step>

  <Step title="Simulate">
    Run it against real chain state. \$0, unsigned, nothing broadcast.
  </Step>

  <Step title="Receipt">
    Does it land, what does it cost, and if not, which class of failure. Plus a binding
    over the exact bytes. See [The Receipt](/receipt).
  </Step>

  <Step title="Someone else signs">
    Gecko hands back the plan, the receipt and the unsigned bytes. A wallet signs.
    `verify_signed_transaction` proves the signed bytes are the checked ones, and
    `submit_transaction` relays them only after that check passes. Different jobs, and
    we do exactly ours.
  </Step>
</Steps>

## The proof

The engine repo's ledger (`docs/mainnet-ledger.jsonl`) holds 50 landed mainnet
transactions as of 2026-09-01. 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 against an exact binding.

They are public and linked on [A real transaction](/mainnet). Open any of them.

## What is not built yet

* **A receipt is true for the state it was taken against, and the binding dies with its
  blockhash** (about 60 seconds). Prepare when you sign. Re-running is free.
* **Nothing re-checks on a schedule.** Drift is detected across runs you make.
* **Seven program configs ship** (Pump.fun, Meteora, Jupiter, ORE, MetaDAO, Orca
  Whirlpool, let\_me\_buy). The catalog lists thousands. Different numbers.
* **Receipts are hosted on one surface.** The orquestra surface simulates against a
  public mainnet RPC and returns a receipt with a binding. The other hosted surfaces give
  tools, not receipts. A fork is your own node.
* **Gecko does not check whether an answer is true**, only that the call is right, and
  on-chain, that the transaction lands.

## One next step

<CardGroup cols={2}>
  <Card title="Evaluating: see it decide" icon="magnifying-glass">
    ```bash theme={null}
    npx @geckovision/gecko@latest prove "buy a token on pump.fun"
    ```

    The whole candidate field, not just the winner, including the accounts it flags
    instead of guessing.
  </Card>

  <Card title="Building: point it at your API" icon="wrench">
    ```bash theme={null}
    npx @geckovision/gecko@latest add https://your-api.com/openapi.json
    ```

    No OpenAPI? Give it the docs URL. Then [Quickstart](/quickstart).
  </Card>
</CardGroup>

<Note>
  `prove` routes and shows provenance with no setup. A **receipt** additionally needs an
  RPC: pass `--rpc-url`, or see [The Receipt](/receipt).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.