solana-api-skill — make any Solana/crypto API first-call-correct

solana-api-skill/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  schedule:
+    # Weekly drift check — re-verify the documented examples against the live APIs,
+    # so an upstream change that breaks a ✅ example surfaces here, not in a user's agent.
+    - cron: "0 13 * * 1"
+
+jobs:
+  validate:
+    name: validate structure
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/validate-skill.sh
+
+  live-examples:
+    name: verify examples against live APIs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Jupiter is keyless and always runs. Helius DAS runs only if the secret is set.
+      - run: bash tests/verify-live-examples.sh
+        env:
+          HELIUS_API_KEY: ${{ secrets.HELIUS_API_KEY }}

solana-api-skill/.gitignore

@@ -0,0 +1,19 @@
+# Secrets — never commit
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+
+# Python / tooling
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

solana-api-skill/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `solana-api-skill` are documented here.
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/); this
+project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-06-30
+
+First draft. The comprehension layer for making any Solana/crypto API
+first-call-correct.
+
+### Added
+- **The spine** — `skill/SKILL.md` plus the four-job method files:
+  - `discovery.md` — pick the right endpoint/method among many.
+  - `access-and-auth.md` — place the credential the docs don't explain; scope/host gating.
+  - `first-call-correct.md` — placement, units, idempotency, enums, identity.
+  - `drift.md` — re-comprehend when the API changes instead of hand-patching.
+- **Marquee playbooks** with verified `❌ wrong → ✅ correct` first calls:
+  - `apis/helius.md` — RPC + DAS; named-object vs positional-array params; key in the URL.
+  - `apis/jupiter.md` — quote → swap; atomic base units; `slippageBps`; echo the whole quote.
+  - `apis/clmm.md` — Orca / Raydium / Meteora; pool-vs-position-vs-mint identity; ticks ≠ prices.
+- **Power-path** — `gecko-surf-power-path.md`: point `gecko-surf` at any OpenAPI for
+  first-call-correct MCP tools.
+- `agents/api-comprehension-engineer.md`, `commands/comprehend-api.md`,
+  `rules/first-call.md`.
+- Copy-only `install.sh`, `README.md`, `SUBMISSION.md`, `LICENSE` (MIT), `VERSION`.
+
+### Notes
+- API specifics verified against official docs / live calls on 2026-06-30. Items
+  that could not be fully verified firsthand are marked `<!-- VERIFY -->` in-file.

solana-api-skill/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md — solana-api-skill
+
+Context for any agent working *in this repo*. (The skill itself, for end users, is
+`skill/SKILL.md`.)
+
+## What this is
+
+A standalone, MIT-licensed skill for the Solana AI Kit: the **comprehension layer**
+that makes any Solana/crypto API **first-call-correct**. An **addon to the core
+[`solana-dev-skill`](https://github.com/solana-foundation/solana-dev-skill)** —
+every other bounty skill teaches one protocol; this teaches the agent to call
+*any* of them correctly the first time.
+
+It ships **no executable logic of its own** beyond a copy-only `install.sh`. The
+content is markdown the agent reads. The optional power-path delegates mechanical
+comprehension to [`gecko-surf`](https://github.com/GeckoVision/gecko-surf) (MIT, on
+PyPI), the engine GeckoVision built.
+
+## Layout
+
+```
+skill/        SKILL.md (entry + routing) → the four-job spine:
+              discovery, access-and-auth, first-call-correct, drift
+              + gecko-surf-power-path (any OpenAPI -> MCP tools)
+              + apis/ (helius, jupiter, clmm — verified ❌→✅ playbooks)
+commands/     /comprehend-api <url> <intent>
+agents/       api-comprehension-engineer (comprehension specialist persona)
+rules/        first-call (opt-in: comprehend before the first call)
+install.sh    copy-only installer · LICENSE (MIT) · README.md · SUBMISSION.md
+VERSION · CHANGELOG.md
+```
+
+## Rules for editing
+
+- **Accuracy over polish.** This is a public competition entry. Every API specific
+  in `skill/apis/` must be verifiable against the official docs or a live call.
+  Anything you can't verify firsthand gets a `<!-- VERIFY -->` marker, not an
+  invented value. The current `<!-- VERIFY -->` items: Helius default DAS `limit`
+  and the `getTransactionsForAddress` method name; Jupiter V2 `/order`+`/execute`
+  details; Meteora `dlmm-api.meteora.ag/pair/all` live body.
+- **The spine is generalizable; the apis/ files are instances.** Keep the four-job
+  procedure in SKILL.md + the method files API-agnostic. Protocol-specific gotchas
+  live only in `skill/apis/`.
+- **No bloat, nothing opaque.** No binaries, no network calls in the installer (kit
+  requirement). Markdown + a copy script only. The power-path `pip install` is the
+  user's explicit, separate action.
+- **Security.** Never put a real API key in an example — use `$HELIUS_API_KEY` /
+  `$JUP_API_KEY` placeholders. The skill teaches *hiding* auth from the tool def
+  and *redacting* it from logs; the repo must model that.
+- **Keep it progressive.** SKILL.md routes; focused files load on demand. Don't
+  inline everything into SKILL.md.
+- **Stay in our lane.** This is the **comprehension/consumption** layer. It is NOT
+  a payment rail and NOT a marketplace; it composes on top of MCP/x402 and consumes
+  a spec as input. If an edit drifts toward either, stop.
+
+## Provider
+
+Built by [GeckoVision](https://geckovision.tech) — the API-comprehension company.
+Engine: [`gecko-surf`](https://github.com/GeckoVision/gecko-surf) ·
+https://pypi.org/project/gecko-surf/. Sibling skill:
+[`solana-token-safety-skill`](https://github.com/GeckoVision/solana-token-safety-skill).

solana-api-skill/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GeckoVision
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

solana-api-skill/README.md

@@ -0,0 +1,170 @@
+# solana-api-skill
+
+**Make any Solana/crypto API agent-usable — first-call-correct.**
+
+An addon to the core [`solana-dev-skill`](https://github.com/solana-foundation/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](https://geckovision.tech)**, the API-comprehension
+company, on top of the open-source engine
+[`gecko-surf`](https://github.com/GeckoVision/gecko-surf) (MIT, on PyPI).
+
+## Quickstart
+
+**Standalone** (Claude Code / Codex / any agent):
+
+```bash
+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](https://github.com/solanabr/solana-ai-kit)** (the bounty's home — 15 agents, 30 commands, MCP, progressive skills):
+
+```bash
+# 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`](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`](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`](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):
+
+```bash
+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
+
+```bash
+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`](https://github.com/GeckoVision/gecko-surf) (MIT) ·
+  https://pypi.org/project/gecko-surf/
+- Provider: [GeckoVision](https://geckovision.tech) — the API-comprehension
+  company. Also ships
+  [`solana-token-safety-skill`](https://github.com/GeckoVision/solana-token-safety-skill).
+
+## 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
+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`](.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.