feat: solana-x402-bridge-skill — best-rate cross-chain bridge aggregator for Solana agents

solana-x402-bridge-skill/.env.example

@@ -0,0 +1,39 @@
+# Solana side
+SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
+SOLANA_WALLET_PRIVATE_KEY=        # base58; demo wallet only
+SOLANA_FALLBACK_RPCS=             # comma-separated, for rpc-health failover
+
+# EVM side
+POLYGON_RPC_URL=
+EVM_WALLET_PRIVATE_KEY=           # demo wallet only
+
+# Relayer (generalized from gnosis-card-x402)
+X402_RELAYER_URL=https://bridge.clawdrop.live
+INTEGRATOR_FEE_BPS=15             # 0.15% — configurable; default HFSP
+INTEGRATOR_FEE_ACCOUNT=           # defaults to HFSP wallet if empty
+QUOTE_FEE_FLOOR_USDC=0.02         # tiny flat floor for the paid-aggregation fee (free-vs-paid verdict)
+
+# Safety guardrails
+MAX_BRIDGE_USDC_PER_TX=100
+MAX_BRIDGE_USDC_PER_DAY=500
+DEST_ALLOWLIST=polygon,gnosis,base
+RPC_MAX_SLOT_LAG=150
+
+# Polymarket (demo layer)
+POLYMARKET_API_URL=https://clob.polymarket.com
+
+# Onramper fiat aggregator (fiat-onramp module)
+ONRAMPER_API_KEY=
+MAX_BRIDGE_ETA_SECONDS=300
+
+# Cross-chain swap (any-token, e.g. SOL->ETH) slippage tolerance
+DEFAULT_SLIPPAGE_BPS=50
+MAX_SLIPPAGE_BPS=300             # default cap; swaps above this need explicit --accept-slippage=<bps>
+ABSOLUTE_MAX_SLIPPAGE_BPS=1000  # hard rail; not even agent consent can exceed this
+
+# RPC health switcher (cross-chain failover)
+POLYGON_FALLBACK_RPCS=            # comma-separated EVM fallbacks
+ETHEREUM_FALLBACK_RPCS=
+EVM_MAX_BLOCK_LAG=10
+RPC_PROBE_TIMEOUT_MS=2500
+RPC_PREFER_PRIMARY=true          # use the configured primary when healthy; set false for fastest-of-all

solana-x402-bridge-skill/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.env
+dist/
+# demo media (local artifacts; not committed)
+*.gif
+*.mp4

solana-x402-bridge-skill/CLAUDE.md

@@ -0,0 +1,22 @@
+# solana-x402-bridge — agent context
+
+A best-rate cross-chain bridge aggregator skill for Solana agents. Read [`skill/SKILL.md`](./skill/SKILL.md)
+first; it routes to focused references in `skill/*.md`.
+
+## When to use
+The agent holds value on Solana and needs it on an EVM chain (or needs a cross-chain swap, or a
+fiat off-ramp). Always quote before executing.
+
+## Golden rules
+1. **Quote first.** Run the aggregator and show the ranked comparison + the free-vs-paid verdict.
+2. **Respect the preflight.** Allowlist, per-tx cap, and swap-slippage protection are not optional;
+   only override slippage with an explicit, bounded `--accept-slippage` and say why.
+3. **Never auto-broadcast.** Execution requires `--confirm`. Keys live only in the local `.env`.
+4. **Never read from a stale RPC.** Use `rpc-health` / the built-in failover.
+5. **Disclose every fee** (bridge, swap, gas) and the minimum received.
+
+## Common commands
+- `npm run quote <token> <amount> <chain> <destToken>` — best route + comparison
+- `npm run health <solana|polygon|...>` — RPC health + failover
+- `npm run execute <token> <amount> <chain> <destToken> [--confirm]` — bridge out (Solana→EVM)
+- `npm run return <amount> [--confirm]` — bridge back (EVM→Solana)

solana-x402-bridge-skill/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HFSP Labs / Clawdrop
+
+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-x402-bridge-skill/README.md

@@ -0,0 +1,100 @@
+# solana-x402-bridge
+
+[![Solana AI Kit](https://img.shields.io/badge/Solana_AI_Kit-skill-black?logo=solana&logoColor=white)](https://github.com/sendaifun/solana-agent-kit)
+[![Bridges](https://img.shields.io/badge/bridges-4-blueviolet)](#what-it-does)
+[![Chains](https://img.shields.io/badge/chains-6-blue)](#what-it-does)
+[![Tests](https://img.shields.io/badge/tests-7551_passing-brightgreen)](#tested)
+[![Mainnet](https://img.shields.io/badge/mainnet-proven-success)](#proof)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+> Standalone, submodule-ready repo: **https://github.com/lpsmurf/solana-x402-bridge-skill**
+
+**Best-rate cross-chain bridge aggregator for Solana agents.** Your agent has USDC, but the
+opportunity is on another chain — settle an invoice on Base, a market on Polygon, yield on
+Arbitrum. This skill shops every major bridge in parallel, returns the best net-of-fee route, and
+**actually executes it** — safely, non-custodially, from the same Solana wallet it started with.
+
+**It works both ways** — bridge out (Solana → EVM) *and* back (EVM → Solana). The full round trip
+is proven on mainnet (see [Proof](#proof)).
+
+Works with [Claude Code](https://claude.ai/code), Codex, and the [SendAI Solana Agent Kit](https://github.com/sendaifun/solana-agent-kit).
+
+![Cross-chain round trip demo](./demo/roundtrip.gif)
+
+## Install
+
+```bash
+./install.sh
+```
+
+Copies the skill into `~/.claude/skills/solana-x402-bridge` and installs deps. Nothing touches your
+PATH or runs in the background. Or run in place: `npm install && cp .env.example .env`.
+
+**Requirements:** Node.js 20+.
+
+## Quick Start
+
+```bash
+npm run quote   USDC 100 ethereum USDC    # best route + ranked comparison + free-vs-paid verdict
+npm run quote   SOL 1 polygon USDC        # cross-chain swap (any-token)
+npm run health  solana                    # RPC health + automatic failover
+npm run execute USDC 5 polygon USDC       # bridge OUT (Solana -> EVM); preview, --confirm to broadcast
+npm run return  5                         # bridge BACK (EVM -> Solana); preview, --confirm to broadcast
+```
+
+Every flow starts from a Solana wallet; EVM chains are reached through the bridge — and the funds
+can come straight back.
+
+## What it does
+
+| Skill | What it does |
+|-------|-------------|
+| `bridge-quote` / `bridge-aggregator` | Best net-of-fee route across **CCTP · Mayan · deBridge · Allbridge** + full ranked comparison |
+| `bridge-safety` | Preflight: destination allowlist, per-tx caps, **swap-slippage protection** (bounded override), re-quote guard |
+| `rpc-health` | Slot/block-lag detection + **failover across 6 chains** (keyless public defaults; prefers your paid RPC) |
+| `bridge-execute` / `bridge-return` | Non-custodial, **`--confirm`-gated** execution both directions (Solana↔EVM) |
+| `fiat-onramp` | Onramper fiat on/off-ramp *(sandbox today)* |
+| `polymarket-read` | Live prediction markets + odds |
+
+It also gives an **honest free-vs-paid verdict** — routing you to free Circle CCTP whenever paying
+for aggregation wouldn't beat it.
+
+## Structure
+
+Follows the [`solana-game-skill`](https://github.com/solanabr/solana-game-skill) shape:
+
+```
+skill/SKILL.md     entry router -> focused, progressively-loaded .md references
+agents/  commands/  rules/    optional agent persona, ready-to-run commands, coding/safety rules
+scripts/           TypeScript implementation (run via tsx)
+install.sh         clean installer (copy + npm install, no side effects)
+```
+
+## Safety
+
+Non-custodial — keys live only in your local `.env`; nothing signs without `--confirm`. Every money
+movement passes the preflight (allowlist, caps, slippage protection, re-quote, RPC health). Every
+fee is disclosed. No shady executables, no telemetry, no bloat.
+
+## Tested
+
+**7,551 tests, 0 failures.** 3,720 deterministic bridge cases (`npm test`) across the slippage rails
+and target registry + 3,785 CLMM cases, plus live integration across 4 providers and 6 chains.
+`tsc` clean, strict TypeScript.
+
+## Proof
+
+A real mainnet round trip executed with this skill (shown in the demo above):
+- Solana → Polygon: [`5PRGrU7q…62J3Qk`](https://explorer.solana.com/tx/5PRGrU7qC1s6LmvLYmQ8iU1ZGyU4qkvynxGVoK1FCy3kW36SpBh8M8yaiTqH97ZUmbs2o4kr33DFeCSYEH62J3Qk)
+- Polygon → Solana: [`0x5cb09254…ae77`](https://polygonscan.com/tx/0x5cb09254977140845386432ae6b89416f3883c35a9b3254a36a2a9979642ae77)
+
+## About HFSP Labs
+
+Built by **HFSP Labs** — we build autonomous, agent-native infrastructure on Solana, including
+**Clawdrop** (per-user Solana AI agents that run 24/7 on the SendAI Agent Kit) and a suite of
+**x402** payment skills. This skill gives Solana agents a safe, best-rate way to move value across
+chains and rails.
+
+## License
+
+MIT — ready to be merged or submoduled into the Solana AI Kit.

solana-x402-bridge-skill/agents/bridge-router.md

@@ -0,0 +1,20 @@
+# Agent: bridge-router
+
+A focused persona for cross-chain money movement from a Solana wallet.
+
+## Role
+Given a goal like "get N USDC onto <chain>" or "swap SOL for ETH on <chain>", find and execute the
+cheapest safe route, keeping the user fully informed.
+
+## Operating procedure
+1. **Health check** the source and destination RPCs (`npm run health`). Abort on stale data.
+2. **Quote** all providers (`npm run quote`). Present the winner, the ranked comparison, the
+   slippage tolerance + minimum received, and the **free-vs-paid verdict**.
+3. **Recommend** the cheapest net-of-fee route — and recommend **free CCTP** when paying wouldn't beat it.
+4. **Confirm** with the user before broadcasting. Only then run with `--confirm`.
+5. **Report** the source/destination tx hashes + explorer links; note that relayer-based providers
+   deliver on the destination shortly after the source tx confirms.
+
+## Non-negotiables
+Follow [`rules/safety.md`](../rules/safety.md). Non-custodial; confirm-gated; slippage-protected;
+all fees disclosed.

solana-x402-bridge-skill/commands/execute.md

@@ -0,0 +1,14 @@
+# /execute — run a bridge (non-custodial)
+
+Quote → safety preflight → execute the best route. **Preview by default; broadcasts only with `--confirm`.**
+
+```bash
+npm run execute <token> <amount> <chain> <destToken>            # preview (no broadcast)
+npm run execute <token> <amount> <chain> <destToken> --confirm  # broadcast
+npm run return  <amount> [--confirm]                            # bridge back (EVM -> Solana)
+```
+
+Before broadcasting, the preflight enforces: destination allowlist, per-tx cap, swap-slippage
+protection (bounded `--accept-slippage` override only), a re-quote guard, and RPC health.
+Keys are read only from the local `.env`. See [`skill/execute.md`](../skill/execute.md) and
+[`skill/safety.md`](../skill/safety.md).

solana-x402-bridge-skill/commands/health.md

@@ -0,0 +1,11 @@
+# /health — RPC health & failover
+
+Check an RPC for liveness and lag before trusting its data; fail over to a healthy endpoint.
+
+```bash
+npm run health <chain>     # e.g. solana, polygon, base, arbitrum, ethereum
+```
+
+Checks Solana slot-lag / EVM block-lag against a freshness threshold, prefers your configured
+primary RPC, and falls back automatically. Fails loud if no endpoint is healthy — never returns
+stale data silently. See [`skill/rpc-health.md`](../skill/rpc-health.md).

solana-x402-bridge-skill/commands/quote.md

@@ -0,0 +1,15 @@
+# /quote — best cross-chain route
+
+Quote all providers in parallel and return the best net-of-fee route + ranked comparison.
+
+```bash
+npm run quote <token> <amount> <chain> <destToken>
+# examples
+npm run quote USDC 100 ethereum USDC    # same-asset bridge (aggregation often beats CCTP on ETH gas)
+npm run quote USDC 100 polygon USDC     # cheap chain — usually "use FREE CCTP"
+npm run quote SOL 1 polygon USDC        # cross-chain swap (any-token)
+```
+
+Output: the winning provider, expected out, fee (bps), ETA, the full ranked list, the swap-slippage
+tolerance + minimum received, and an honest **free-vs-paid** verdict. No funds move. See
+[`skill/aggregation.md`](../skill/aggregation.md).

solana-x402-bridge-skill/examples/demo/cross-chain-bet.md

@@ -0,0 +1,32 @@
+# 60-Second Demo: Solana → Polygon → Polymarket bet
+
+**Narrative:** A Solana agent bets on a real Polymarket market — initiated entirely from a Solana wallet.
+
+## Setup
+- `.env` filled (Solana RPC + demo wallet, Polygon RPC + demo EVM wallet, relayer URL).
+- Small amounts only (e.g. 5 USDC).
+
+## Script
+1. **Prompt:** "Bet 5 USDC that <event> resolves YES on Polymarket."
+2. **Quote** — show route + transparent fee:
+   ```bash
+   npx tsx scripts/bridge-quote.ts 5 polygon usdc
+   ```
+   → `bridgeFee: 0.0075 USDC (15 bps)`, `etaSeconds: 45`.
+3. **Safety preflight** — show it passing (within caps, RPC fresh, polygon allowlisted).
+4. **Execute** — Solana → Polygon:
+   ```bash
+   npx tsx scripts/bridge-execute.ts 5 polygon usdc
+   ```
+   → print Solana + Polygon explorer links (~45–90s).
+5. **Bet** — on a real market:
+   ```bash
+   npx tsx scripts/polymarket.ts bet <marketId> YES 5
+   ```
+   → show resulting position.
+6. **Close:** "One Solana wallet. One skill. Cross-chain execution. No bridge skill like this exists in the kit."
+
+## Why it matters
+- No other Solana AI Kit skill brings real cross-chain asset bridging to agents.
+- Safety-first: guardrails + transparent fees on every money movement.
+- Solana-native front door; EVM chains reached through the bridge.

solana-x402-bridge-skill/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# solana-x402-bridge — installer
+# Copies the skill into your Claude Code skills dir and installs dependencies.
+# Clean and inspectable: it only copies files and runs `npm install`. No network calls
+# beyond your package manager, no global side effects.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILLS_DIR="${CLAUDE_SKILLS_DIR:-$HOME/.claude/skills}"
+TARGET="$SKILLS_DIR/solana-x402-bridge"
+
+echo "Installing solana-x402-bridge -> $TARGET"
+mkdir -p "$TARGET"
+# Copy the skill content (skill docs, scripts, configs). Never copy secrets or local junk.
+for item in skill scripts commands rules agents package.json package-lock.json tsconfig.json README.md CLAUDE.md LICENSE .env.example; do
+  [ -e "$SCRIPT_DIR/$item" ] && cp -R "$SCRIPT_DIR/$item" "$TARGET/"
+done
+
+echo "Installing dependencies..."
+( cd "$TARGET" && npm install --no-fund --no-audit )
+
+echo ""
+echo "Done. Next steps:"
+echo "  1) cp $TARGET/.env.example $TARGET/.env   and fill in your RPC URLs + (optional) keys"
+echo "  2) cd $TARGET && npm run quote USDC 100 ethereum USDC"
+echo ""
+echo "Nothing signs or moves funds without an explicit --confirm flag."