gecko-surf — make any API agent-usable without integration code

Gecko is the comprehension layer for the agentic economy. 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 write, no guessing whether the agent is calling it right.

Docs and endpoints are built for humans. Gecko translates them for agents.

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/docs), 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

Gecko composes on top of x402 / MCP / pay.sh — it consumes a payment catalog 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.

⚠️ Status (honest)

V1 is live on mainnet, end-to-end, against the real TxODDS World Cup API: ingest → comprehend → catalog → access (a two-token on-chain subscribe) → first-call-correct → real data. A $0 recorded mode runs the entire path offline with no subscription. 343 tests pass.

What is not proven: consumer willingness-to-pay — the actual decider for the business. That is discovery-interview work, not a demo claim. So: never read this repo as "Gecko is a proven business." What is real today is a working comprehension path on one genuinely painful API, and a clean, API-agnostic engine behind it.

Watch it run — the 70-second launch demo

Three acts, every number from a real run:

• Plug in a paywalled API (TxODDS) → 18 ops comprehended, 8/8 first-call-correct, live World Cup odds.
• Stay safe → a poisoned spec that drains a naive agent 8/8 is blocked 0/8, benign calls still served — caught in simulation, before any signature exists.
• Stay correct → gecko test writes 32/32 first-call-correctness checks and emits them to CI.

Architecture

Gecko is a control plane, not a data plane. It 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 any API unilaterally.

flowchart TD
    A["AI agent<br/>(has a goal, no API docs)"] -->|"what can this API do for X?"| S

    subgraph SC["Gecko — comprehension layer (control plane)"]
        direction TB
        ING[("ingest<br/>OpenAPI / docs — the *surface* only")]
        CAT["catalog<br/>intent → endpoint"]
        TOOL["tools<br/>question-shaped, first-call-correct<br/>(auth hidden)"]
        ACC["access<br/>subscribe / session handshake"]
        ING --> CAT --> TOOL
        TOOL --> ACC
    end

    S --> TOOL
    ACC -->|"injects auth"| CALL
    A -->|"calls the real API directly"| CALL["the real API<br/>(data plane — Gecko never stores it)"]
    CALL -->|"data"| A

1. Ingest the API surface (OpenAPI 3.x) → normalized operations + params ($ref resolved, cycle/depth guarded). Never the response data.
2. Catalog — a structured capability list (intent → endpoint). Lexical at this scale; no vectors.
3. Comprehend — each operation becomes a question-shaped tool def an agent picks correctly with no API docs. Auth headers are hidden.
4. Access — drive the access/subscription handshake; the 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.
6. Validate — replay calls, confirm first-call-correct, log outcomes (JSONL). That log is the seed of the V2 correctness corpus — the compounding moat.

What you get

Make any API agent-usable

Point it at an OpenAPI and your agent can call it — no client code, auth handled, first call correct.

Serve it to your agent over MCP — prints the MCP URL + one-click "add to Claude / Cursor" strings:

# no install — run it straight from PyPI:
uvx --from "gecko-surf[serve]" gecko <openapi-url>
# or install the CLI (any system, no Python prereq):
curl -fsSL https://get.geckovision.tech/install.sh | bash
gecko <openapi-url>

It prints the comprehension summary, the MCP URL, and a one-click claude mcp add / Cursor / VS Code string — then serves the API to your agent over Streamable-HTTP.

Or embed the SDK in your own app:

from gecko import AgentApiClient, public_session

client = AgentApiClient(spec, session=public_session())
hit = client.search("what you want")[0]            # intent → right endpoint
client.call(hit["name"], {...}, mode="recorded")   # correct call; "live" for real data

A complete forkable example: examples/_starter/ — an app on any API in ~20 lines, runnable at $0. For a full agent (Telegram + an LLM tool-loop), see examples/sos_vzla_bot/.

Develop / falsify offline ($0, no keys, no subscription)

git clone https://github.com/GeckoVision/gecko-surf
cd gecko-surf && uv sync
uv run pytest                       # 343 passing
uv run python -m gecko.demo      # E2E: goal → discover → correct call → data (recorded, $0)

The recorded demo runs the same code path as live — it just synthesizes responses from the schema instead of hitting the network. That's the point: you can falsify the comprehension offline before spending a cent.

Going live (real World Cup data)

Recorded mode needs no subscription. For live data, do the one-time on-chain subscribe — see scripts/SUBSCRIBE.md — then pass a real Session:

from gecko.client import AgentApiClient
client = AgentApiClient(spec, base_url="https://...", session=my_session)
client.call(tool, args, mode="live")   # same path as recorded

Mainnet boundary: the subscribe transaction is founder-run only. The tooling simulates (no spend) and hands over the exact command; a human broadcasts.

What's in this repo

Rule: the comprehension logic is the product and lives in gecko/. The MCP server, the client, and scripts are thin transport.

Stack

Environment variables

Source of truth: .env.example.

Recorded mode and the test suite need no keys.

Development

uv run ruff format && uv run ruff check --fix
uv run mypy gecko
uv run pytest                       # targeted invocations preferred
uv run python -m gecko.demo      # $0 recorded smoke

See CLAUDE.md for the architecture invariants, the subagent team, and conventions.

Team

• Ernani (@ernanibritto) — Technical co-founder. Builds the Gecko engine end-to-end: ingest, comprehension, the access layer, and the MCP surface.
• Leticia (@0xLeti) — Co-founder, Product Designer. 8+ years designing for enterprises and startups; ex-Liga Ventures.

License

Apache License 2.0 — see LICENSE and NOTICE. Apache-2.0 carries an explicit patent grant. The engine is open (the distribution funnel); the correctness corpus and hosted layer stay private (open-core).

The comprehension layer for the agentic economy.