Surf

[Gecko — the web wasn't built for agents. Yet.]

Stop letting your agent guess

Check the call before it counts. Gecko is open-source and runs on your machine:
one command maps any API — messy, paywalled, or on-chain — into a call graph your agent
checks instead of guesses from, and anything that spends is simulated to a receipt first.
No wallet, no payment rail, no key held — 64 mainnet transactions, 49 with a cost predicted before signing, 47 of those exact to the unit (re-read from the chain, 2026-09-19).

[Python 3.11+] [MCP] [tests] [Apache 2.0] [x402]

Quickstart · Docs · Architecture · FAQ · Security

Built for the calls your agent must not get wrong. Two axes, either one qualifies: a messy surface (paywalled, drifting, undocumented, on-chain) or a high-stakes action (your agent runs unattended with credentials or money).

What Gecko is

Gecko is an open-source knowledge graph built specifically for AI agents that call APIs. Point it at an OpenAPI spec, a docs site, or a Solana program's IDL and source, and it reads that surface into a graph your agent traverses — every fact tagged with where it came from, and anything it cannot establish flagged rather than guessed.

A specification tells your agent what a call looks like. It cannot tell it whether the call will work. That gap is in every spec, including a perfect one, and it is where agents fail expensively: not on the call that errors, but on the call that is accepted and wrong. Gecko closes it by handing back one specific call — and, for anything that spends, by simulating that call against real state first and returning a receipt.

It is not the agent and not an orchestrator. It holds no key, signs nothing, broadcasts nothing, and stores no response payload — it stores surfaces and correctness metadata, never your data.

Quick start

No install:

npx @geckovision/gecko doctor              # 1. check your environmentnpx @geckovision/gecko add <spec-or-docs>  # 2. comprehend it — $0, no live callnpx @geckovision/gecko report <spec>       # 3. get the scorecard — grade + findingsnpx @geckovision/gecko serve <spec>        # 4. your agent uses it over MCP

Or install once:

npm install -g @geckovision/gecko          # prebuilt binary — no Python neededuv tool install "gecko-surf[serve]"        # or pip, if you want the Python package
gecko add <spec-or-docs>

Plug into your agent:

# Claude Codeclaude mcp add my-api -- npx -y @geckovision/gecko serve <spec> --stdio
# Cursor / VS Code / any MCP client — mcp.json{ "mcpServers": { "my-api": { "command": "npx", "args": ["-y", "@geckovision/gecko", "serve", "<spec>", "--stdio"] } } }

Going live is a separate, deliberate step:

gecko auth set <provider>                  # key goes to your OS keychain — never mcp.json

Then your agent asks questions, not endpoints:

Which fixtures kick off in the next hour, and what are the current odds?What is the peg state of USDC right now?Plan a swap of SOL for USDC on Meteora, bin_step 4.

Why

An OpenAPI says what exists. An IDL says what a program looks like. Neither is enough to act:

• Docs drift. Working integrations broke twice in 2026 from silent layout changes.
• IDLs drop facts. A required Pump.fun account never appears in the IDL at all.
• Agents guess. A wrong guess posts a charge, reverts a transaction, burns fees.

Gecko replaces the guess with a graph:

• Every edge carries provenance — extracted from the surface, recovered from source, or honestly flagged as unknown. Never fabricated.
• Every action can be verified first — simulated on a $0 mainnet fork to a receipt: pass, or a classified revert, before any spend.
• Every failure teaches — outcomes land in a categorical corpus; a drift series flags when a provider ships a change that breaks a working call.
• Auth is invisible to the agent — keys injected at call time from your keychain. The model never sees a credential.

Under the hood

Most agent-tool layers are thin wrappers. Gecko is a memory substrate, and three of its design choices are deliberately different from the textbook:

And the depth is measured, not asserted:

• The overlay artifact. For every auto-comprehended program, Gecko emits the exact list of facts that could not be derived from any public surface (overlays/) — the value of comprehension, quantified per program.
• Seven security layers, fail-closed: spec sanitizer · per-tool quarantine · image Skill Guard · SSRF netguard · out-of-band auth anchoring · verdict signing gate · an AST-enforced never-sign boundary.
• The numbers: 5,043 tests · 64 mainnet transactions, 47/49 predictions exact · 5 paid by a fee relay, the buyer holding no SOL, the last four a USDG→USDC→purchase route · 8 Solana programs wired, 4 differential-proven · 2 live receipt-pairs · −77%/−89% measured context cuts · a 4,534-program catalog listed · 0 auth headers exposed across 14 real specs.

Explore the diagrams: architecture on docs.geckovision.tech (all three views, rendered) · the map in this repo

Proof, not promises

Live, on a mainnet fork, $0:

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.

Use cases

TxLINE (paywalled sports odds) — without vs with Gecko

[70-second demo — 18 first-call-correct tools, 8/8 poisoned attacks blocked, 32/32 correctness checks] · MP4

Cross-API correlation — three APIs, one question

Pegana × Birdeye × Jupiter joined on a declared entity; the agent plans across surfaces first-try. Try it: gecko graph svg <spec> renders any surface's call graph.

Solana programs — buy a coffee on mainnet

Everything above is a $0 fork. This one is not: real mainnet, real USDC, a real espresso.

let_me_buy is a storefront program on Solana. A merchant stands up a store and lists products priced in USDC; a buyer scans a QR code and pays. One account per store — PDA(["receipts", store_name]) — holds the menu, the receipts, the running count and the merchant's authority.

[An agent resolves a store name to its own on-chain accounts, predicts the compute cost, signs in an enclave, and settles a real 0.1 USDC espresso on Solana mainnet]

MP4 version — one unedited take. The receipt says 24,956 CU before anything is signed; the chain charges 24,956 CU (4X8dCyZU…, slot 439046190). The key never leaves its enclave.

uvx --from "gecko-surf[serve,solana]" gecko-orquestra --program let_me_buy --stdio

Two facts the IDL does not carry, and both break the call:

• mark_as_delivered declares its receipts seed as store_name, but that instruction's own arguments are _store_name and receipt_id. The seed names an argument that does not exist, so a deriver resolving seeds by argument name gets nothing for the one seed that selects the store. Gecko binds by seed value.
• In make_purchase the store's authority is writable but not a signer. The buyer pays from ATA(signer, mint); the store is credited at ATA(authority, mint) — same mint, different owner. Derive both from one owner and you have built a purchase that pays the buyer back. Gecko refuses that plan before a builder is ever asked.

The prediction tracks state, not a memorised constant. Three purchases at this one storefront were charged 23,789 → 24,183 → 24,956 CU; the last two are the same product. Each sale appends a receipt to the store's account, so the program does more work — and the receipt predicted the new number each time it was asked.

Gecko recovers what the surface drops, Orquestra builds the instruction, and the receipt says whether it lands — before any signature.

Architecture

[Gecko architecture — untrusted surfaces → provenance knowledge graph → verified action (simulate → receipt → external signer)]

Control plane, never data plane. Gecko stores surfaces + correctness metadata — never response payloads, user data, or secrets.

1. Ingest — OpenAPI / docs / IDL / program source → sanitized, quarantine-checked.
2. Comprehend — normalized ops, recovered PDA seeds, generated configs + measured overlays.
3. Know — the provenance graph (surface, program, cross-API joins).
4. Project — question-shaped tools over MCP; auth stripped; −77%/−89% context cuts measured on two real specs.
5. Verify — plan → external builder → simulate → receipt → fail-closed signing gate. Gecko never signs, never broadcasts.
6. Learn — categorical outcomes → drift series → back into the graph.

Interactive diagrams · llms.txt · Receipt semantics

What you get

Skills

The engine is the product; the skills are how an agent learns to drive it. Six of them ship as one plugin — markdown the agent reads, no executable logic of its own.

/plugin marketplace add GeckoVision/gecko-surf/plugin install gecko-surf@geckovision

The two defense skills are one disease with two deliveries: a poisoned spec aims at what your agent calls, a poisoned artifact aims at what your agent does. Full map and status in skills/README.md.

Modes

• Recorded (default): $0, schema-synthesized responses, fully offline. Falsify everything before any live call.
• Live: same code path; credentials injected from your keychain at the edge. gecko auth set <provider> — deliberate, never implicit.

Hosted

The engine in this repo also runs at mcp.geckovision.tech — comprehended surfaces served over Streamable-HTTP MCP, keys injected server-side. Developers never pay; providers pay a flat price per API. Gecko takes no cut, holds no funds, signs nothing. → docs.geckovision.tech

Repo map

Development

uv run ruff format && uv run ruff check --fixuv run mypy geckouv run pytest                # 5,043 passinguv run python -m gecko.demo  # $0 recorded E2E

Contributing

PRs welcome. Run the toolchain above before pushing. Security findings → SECURITY.md.

License

Apache-2.0 — see LICENSE.