solana-api-skill

Make any Solana/crypto API agent-usable — first-call-correct.

An addon to the core solana-dev-skill. A progressive, token-efficient skill that teaches a coding/trading agent a generalizable procedure for calling an unfamiliar Solana or crypto API and getting the first call right — the right endpoint, the credential in the right place, the exact request shape, and a drift-aware version pin.

Built by GeckoVision, the API-comprehension company, on top of the open-source engine gecko-surf (MIT, on PyPI).

Quickstart

Standalone (Claude Code / Codex / any agent):

git clone https://github.com/GeckoVision/solana-api-skill && cd solana-api-skill
bash install.sh        # copy-only into ~/.claude — no binaries, no network

With the Solana AI Kit (the bounty's home — 15 agents, 30 commands, MCP, progressive skills):

# 1) install the kit (Claude Code plugin)
/plugin marketplace add solanabr/solana-ai-kit
/plugin install solana-ai-kit@stbr
# 2) add this skill on top (or submit it to the kit's ext/ so SKILL.md routes to it)
bash install.sh

The kit's SKILL.md hub loads skill files on demand; solana-api-skill slots in as the API-comprehension layer its protocol skills sit on top of. Then drive it via the api-comprehension-engineer agent or /comprehend-api <api-or-openapi-url> <intent>.

The gap it fills

Across 100+ open skill-bounty PRs, every skill teaches ONE protocol. None makes an agent first-call-correct against any Solana/crypto API. That's the hole this fills. This is the comprehension layer the others sit on top of: a single-protocol skill assumes the agent already knows how to call that protocol; this skill is the procedure for when it doesn't.

The problem isn't missing docs. Docs are written for humans — prose, scattered examples, the auth handshake assumed, units implied. An agent reading them one-shot picks the wrong method, forgets the key, sends a UI amount where atomic units are required, or PUTs a field the API wants in the query string. Each miss is a failed call, a retry, a burned credit.

What it does — the four jobs

Turn any API surface into a correct call by getting four things right:

#	Job	The question it answers
1	Discovery	Of hundreds of methods, which one answers this intent?
2	Access & Auth	What credential goes where (URL? header? body?), at what scope?
3	First-call-correct	The exact shape — path vs query vs body, units, idempotency, enums?
4	Drift	The API changed. Re-comprehend it — don't hand-patch one call.

Get these four right and the first call lands. Get one wrong and it doesn't.

Marquee playbooks (real APIs, real gotchas)

Each ships a verified ❌ the call an agent gets wrong → ✅ the correct first call:

• Helius (RPC + DAS) — DAS methods take a named object, not a positional array; the API key lives in the URL. → skill/apis/helius.md
• Jupiter (quote → swap) — amount is atomic base units (lamports), not a decimal; slippageBps is basis points; POST the whole quote object. → skill/apis/jupiter.md
• CLMM (Orca Whirlpools / Raydium CLMM / Meteora DLMM) — pass the pool/position pubkey, not a token mint; a tick is not a price. → skill/apis/clmm.md

The power-path (any OpenAPI, no hand-written file)

For an API not covered above, comprehend it mechanically. gecko-surf turns any OpenAPI 3.x spec into first-call-correct, question-shaped MCP tools (auth hidden, units and placement resolved):

pip install "gecko-surf[serve]"
gecko https://api.example.com/openapi.json   # serves first-call-correct tools over MCP

PyPI: https://pypi.org/project/gecko-surf/ · source: https://github.com/GeckoVision/gecko-surf

Install

git clone <this-repo> && cd solana-api-skill
bash install.sh          # copies the skill + command + agent + rule into ~/.claude

Or point it at a custom config dir: CLAUDE_DIR=/path bash install.sh. The installer is copy-only — no binaries, no network calls. The power-path is a separate, explicit pip install you run yourself.

Use

• Ask your agent: "make a first-call to Helius getAssetsByOwner for <wallet>" or "quote 1.5 SOL → USDC on Jupiter."
• Command: /comprehend-api <api-or-openapi-url> <intent>
• Agent persona: api-comprehension-engineer runs the full four-job flow.
• Rule: first-call — comprehend before the first call; never brute-force a 4xx.

Structure

skill/
  SKILL.md                  entry point + routing (load this)
  discovery.md              Job 1 — pick the right call among many
  access-and-auth.md        Job 2 — the key/header/scope handshake the spec omits
  first-call-correct.md     Job 3 — placement, units, idempotency, enums, identity
  drift.md                  Job 4 — re-comprehend on change; don't hand-patch
  gecko-surf-power-path.md  point gecko-surf at any OpenAPI -> first-call-correct MCP tools
  apis/
    helius.md               RPC + DAS (named object vs array; key in URL)
    jupiter.md              quote -> swap (atomic units; bps; whole quote)
    clmm.md                 Orca / Raydium / Meteora (pool vs position vs mint; ticks)
commands/
  comprehend-api.md         /comprehend-api <url> <intent>
agents/
  api-comprehension-engineer.md   comprehension specialist persona
rules/
  first-call.md             opt-in: comprehend before the first call
install.sh                  copy-only installer (no binaries, no network)
CLAUDE.md · LICENSE (MIT) · README.md · SUBMISSION.md · VERSION · CHANGELOG.md

How it works

The skill ships no executable logic of its own beyond the copy-only installer — it's markdown the agent reads. The optional power-path delegates the mechanical work to gecko-surf, which ingests an OpenAPI spec, builds an intent→endpoint catalog, generates question-shaped tools with auth hidden, and serves them over MCP. gecko-surf is control-plane only — it stores the API surface and correctness metadata, never your response payloads, user data, or secrets.

• Engine: gecko-surf (MIT) · https://pypi.org/project/gecko-surf/
• Provider: GeckoVision — the API-comprehension company.

Tested against live APIs

The whole point of this skill is first-call-correctness + drift-resilience — so its own examples are tested against the real endpoints, not just asserted in prose.

bash scripts/validate-skill.sh        # structure, frontmatter, links + flags unverified claims
bash tests/verify-live-examples.sh    # runs the documented ❌→✅ calls against the LIVE APIs

• verify-live-examples.sh fires the documented Jupiter calls (keyless) and asserts the documented behavior: amount=1.5 → HTTP 400, amount=1500000000 + slippageBps=50 → echoed back, routePlan present. Helius DAS runs when HELIUS_API_KEY is set (named-object → result; positional array → error).
• CI (.github/workflows/ci.yml) runs both on every push and weekly on a schedule — so if an upstream API drifts and breaks a ✅ example, it fails here, not in a user's agent. The skill that teaches drift-resilience is itself drift-tested.
• validate-skill.sh also lists any <!-- VERIFY --> claims still to pin before publishing.

License

MIT — ready to be merged or submoduled into the kit.