Example: TxLINE trading agent

A complete, runnable use case for the whole thesis on one painful, paywalled API. A trader wants a Solana agent that watches the World Cup and settles prediction markets. Starting from nothing — with Gecko as the brain and a policy-gated wallet as the hands — the agent comprehends TxLINE (odds behind a two-token on-chain paywall), flags sharp moves, and settles a market against TxLINE’s on-chain Merkle proof. The user reads no docs and writes no integration code. It runs $0 offline (recorded feed + a sandbox wallet); mainnet swaps only the signer edge.

See the whole thing in one run

git clone https://github.com/GeckoVision/gecko-surf && cd gecko-surf && uv sync
uv run python -m examples.txline_sharp_agent.story

User sets up the agentic wallet — the only manual steps

The user’s entire on-chain surface is three acts: fund a wallet, set it up once, and authorize one policy (spend ≤ $50 for {subscription, settlement}). Nothing else is on the user — the agent does the rest.

Gecko comprehends the paywalled TxLINE API

One line turns TxLINE into 18 first-call-correct tools. Auth-gated odds tools stay hidden until a session can satisfy them, so the agent can’t mis-call what it can’t see. No docs, no hand-written client.

npx @geckovision/gecko add \
  examples/txline_demo/spec/txline_openapi.yaml \
  --base-url https://txline.txodds.com --mode recorded

Agent subscribes to TxLINE — the wallet signs within the policy

The agent builds the on-chain subscribe transaction; the wallet signs it within the authorized policy. Gecko never touches a key.

Agent monitors the odds and flags a sharp move

Successive odds snapshots run through the detector; a shift past the threshold is the trading signal: fixture 42 · Home 45.6% → 54.8% (+9.2pp) ⚡.

Agent settles the market on TxLINE's Merkle proof — the wallet signs

Every TxLINE call is risk-scored by the security gateway. The agent maps the 3-stage Merkle proof onto the on-chain validate_stat instruction and the wallet signs the settle — the program never decides the outcome, the proof does.

The user did 3 acts (fund · set up · authorize). The agent comprehended a paywalled API, subscribed, caught the move, and settled a market — the wallet signing only within the policy, Gecko never holding a key or a dollar.

The agentic wallet in the middle

1 · Fund

The user funds the wallet with the budgeted USDC. Funding is always the user’s side.

2 · Set up

One-time wallet setup (social login on a Privy/Phantom embedded wallet, or a pay --sandbox ephemeral wallet for the $0 demo).

3 · Authorize

One policy: a spend cap + an allow-list of purposes. The wallet signs only within it — an over-cap request is refused.

Gecko is the brain; the wallet is the policy-gated hands. They meet at a WalletSeam — an injected boundary, exactly like Gecko’s Session seam — so the wallet is pluggable and Gecko is never the signer.

Mainnet hands: Privy (Solana instruction-level policy enforced in-enclave at signing) or Phantom (embedded wallet + social login, MCP-native). OKX OnchainOS is a valid alternate.
The rail: pay.sh sits on top as the x402 payment rail — the wallet signs, the rail settles. (pay.sh is a rail, not a wallet.)
Deferred: MagicBlock — its session keys only bind if the counterparty program integrated them, so they don’t provide bounded authority for an arbitrary third-party API.

Gecko is control-plane only — it never holds keys, funds, or response payloads. The offline sim profiles transactions (via Surfpool’s surfnet_profileTransaction) and never signs or broadcasts. A real mainnet settle is always the user’s own signed action, under the policy they pre-authorized.

Break it into parts

Each piece runs on its own, $0 and offline:

Command	What it shows
`python -m examples.txline_sharp_agent.story`	The whole use case, end to end
`python -m examples.txline_sharp_agent.demo`	Comprehension + first-call-correct call + sharp-move detection
`python -m examples.txline_sharp_agent.settlement_sim`	A flagged move → the on-chain `validate_stat` settlement plan
`python -m examples.txline_sharp_agent.wallet_sim`	The 3-step agentic wallet, policy-bounded

The example also bundles curated Solana subagents (defi-engineer, solana-architect, solana-qa-engineer) and a Surfpool MCP config, so a forked project can build the on-chain settlement side. See the example’s README on GitHub.

Going live

Recorded mode needs nothing. For live TxLINE data the user completes an on-chain subscription (fund a wallet + sign — their action); the agent drives the guest → subscribe → activate handshake and Gecko seals the two tokens in the OS keychain. Same tool-building code path — only the transport edge changes. See Access & auth.

Fork it for your own API

gecko add <your-api> and your agent is calling it correctly, first try — then integrate a policy-gated wallet the same way.

Get Started

How it works

For AI agents

For API providers

Reference

Example: TxLINE trading agent

See the whole thing in one run

The agentic wallet in the middle

1 · Fund

2 · Set up

3 · Authorize

Break it into parts

Going live

Fork it for your own API

​See the whole thing in one run

​The agentic wallet in the middle

1 · Fund

2 · Set up

3 · Authorize

​Break it into parts

​Going live

Fork it for your own API

See the whole thing in one run

The agentic wallet in the middle

Break it into parts

Going live