Solana Easy Swap

Swap any Solana token from chat. Say 'swap 1 SOL for USDC' and it handles everything — quoting, signing, sending, confirming. No API keys, no wallet extensions, no setup beyond a keypair. Powered by Jupiter. Use when a user wants to swap, trade, exchange, buy, or sell Solana SPL tokens, SOL, USDC, memecoins, or any token pair on Solana.

Security Scan

The skill does what it claims: it uses a local Solana keypair to build, sign, and submit Jupiter-powered swaps; the requested binaries/env vars and network calls are proportional to that purpose.

Purpose & Capability

Name/description (swap SPL tokens using a local keypair and Jupiter) align with the actual requirements: node binary, a SOLANA_KEYPAIR_PATH pointing to a local keypair, and a script that calls Jupiter and the Solana RPC. There are no unrelated credentials, unknown third-party hosts, or unrelated binaries requested.

Instruction Scope

SKILL.md instructs the agent to read the keypair (declared env var), call prepare/execute/status/receipt via the provided CLI, show the prepare summary and obtain user confirmation before executing. The runtime instructions and the included script operate only on swap-related data, call Jupiter endpoints and the Solana RPC, and store prepared-swap metadata under a local .cache path. The instructions do not ask the agent to read unrelated files or exfiltrate secrets.

Install Mechanism

There is no remote arbitrary-download installer. The metadata recommends running npm install in the skill directory; the package.json and package-lock reference standard npm packages (e.g., @solana/web3.js, bs58). No URL shorteners, personal servers, or extracted archives are used in the install spec.

Credentials

Only SOLANA_KEYPAIR_PATH is required (plus optional RPC and slippage envs). That is proportional: signing transactions requires access to a private key. No unrelated secrets or multiple service credentials are requested. Note: access to the keypair grants the ability to sign and spend funds from that account — this is expected but high-risk in practice.

Persistence & Privilege

The skill is not force-installed (always: false) and does not request system-wide privileges. It writes prepared-swap JSON files into a local .cache directory within the skill path and does not modify other skills or global agent settings. Agent autonomous invocation is allowed by default but is not unusual; the skill's own guidelines require explicit user confirmation before sending transactions.

Assessment

This skill is internally consistent and appears to be what it claims: it will read the keypair file you point it to, query Jupiter, build and sign transactions, and submit them to your chosen Solana RPC. That is expected behavior for an on-device swap tool, but be aware of the security implications: granting SOLANA_KEYPAIR_PATH means the skill (when run) can sign/spend from that wallet. Only use a keypair you trust the skill to access (consider a dedicated low-balance wallet for testing). Review the script (scripts/swap.mjs) yourself before installing, keep npm installs isolated (use a container or VM if unsure), and ensure the agent prompts you and never executes swaps without your explicit confirmation. If you need higher assurance, use a hardware wallet or a workflow that never exposes private key material to third-party code.

Swap any Solana token from chat. Say "swap 1 SOL for USDC" and it handles everything — quoting, signing, sending, confirming. No API keys, no wallet extensions, no setup beyond a keypair. Powered by Jupiter.

Setup

First run: Install dependencies (automatic if install spec is supported, otherwise manual):

cd {baseDir} && npm install --production

Required env var:

• SOLANA_KEYPAIR_PATH — path to a Solana keypair JSON file (standard solana-keygen format). This skill reads your keypair to sign transactions. Only use with a keypair you trust this skill to access.

Optional env vars:

• SOLANA_RPC_URL — custom RPC endpoint (default: https://api.mainnet-beta.solana.com)
• OSS_DEFAULT_SLIPPAGE_BPS — default slippage in basis points (default: 100 = 1%)
• OSS_PRIORITY_FEE_FLOOR — minimum priority fee in lamports (default: 50000)

No API keys required. Jupiter is used unauthenticated.

Common Token Mints

Token	Mint
SOL (wrapped)	So11111111111111111111111111111111111111112
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB

For other tokens, ask the user for the mint address.

Flow

1. Prepare

node {baseDir}/scripts/swap.mjs prepare \
  --from So11111111111111111111111111111111111111112 \
  --to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --amount 1000000000 \
  --slippage 100

Returns JSON:

{
  "prepareId": "abc123",
  "expectedOut": "150230000",
  "minOut": "148727700",
  "priceImpact": "0.01",
  "expiresAt": "2025-02-13T20:00:00Z",
  "summary": {
    "from": "1 SOL",
    "to": "~150.23 USDC",
    "minReceived": "148.73 USDC",
    "slippage": "1%",
    "priceImpact": "0.01%",
    "destination": "owner"
  }
}

Always show the summary to the user and wait for confirmation before executing.

If priceImpact > 1%, warn the user explicitly.

2. Execute

After user confirms:

node {baseDir}/scripts/swap.mjs execute --prepareId abc123

Returns JSON:

{
  "signature": "5UzV...",
  "submittedAt": "2025-02-13T19:58:12Z"
}

3. Status (poll until confirmed)

node {baseDir}/scripts/swap.mjs status --signature 5UzV...

Returns JSON:

{
  "state": "confirmed",
  "slot": 123456789,
  "confirmationStatus": "finalized"
}

States: submitted → confirmed | failed | expired | unknown

4. Receipt

node {baseDir}/scripts/swap.mjs receipt --signature 5UzV...

Returns JSON with actual amounts swapped, fees, and a Solscan link.

Error Handling

All commands return JSON with error field on failure:

{
  "error": {
    "code": "INSUFFICIENT_SOL",
    "message": "Not enough SOL for fees. Have 0.001, need ~0.006",
    "retryable": false
  }
}

Error codes and retry guidance:

Code	Retry?	Action
INVALID_INPUT	No	Fix the input
INSUFFICIENT_SOL	No	Tell user they need more SOL
KEYPAIR_NOT_FOUND	No	Check SOLANA_KEYPAIR_PATH is set
KEYPAIR_INVALID	No	Check keypair file format
PREPARE_EXPIRED	Yes	Run prepare again, re-confirm with user
PREPARE_ALREADY_EXECUTED	No	This swap was already sent
BACKEND_UNAVAILABLE	Yes	Wait 3s, retry prepare up to 2x
BACKEND_QUOTE_FAILED	No	No route — tell user (bad pair or no liquidity)
TX_EXPIRED	Yes	Run prepare again, re-confirm with user
TX_BROADCAST_FAILED	Yes	Retry execute once (if not expired)
TX_FAILED_ONCHAIN	No	Swap failed (e.g., slippage). Do NOT retry.
RPC_UNAVAILABLE	Yes	Wait 3s, retry up to 2x

Agent Guidelines

1. Always confirm before executing. Show the user the summary from prepare and wait for explicit "yes" / "go" / "confirm".
2. Never auto-retry failed onchain transactions. If TX_FAILED_ONCHAIN, the tx landed and failed — retrying sends a new tx.
3. Re-confirm on re-prepare. If you need to prepare again (expired quote), show the new summary — prices may have changed.
4. Handle amounts in base units. SOL = 9 decimals (1 SOL = 1000000000), USDC = 6 decimals (1 USDC = 1000000).
5. Ask for mint addresses if the user mentions a token you don't recognize. Don't guess.
6. Report the Solscan link after confirmation: https://solscan.io/tx/{signature}

Security

• This skill signs transactions using the configured keypair. It does NOT create, import, or manage keys.
• Keypair material is never logged, echoed, or included in any output.
• Third-party destinations require explicit --allowThirdParty flag.
• All swaps enforce slippage protection via minOut.
• Prepared swaps expire after 120 seconds by default.

Limitations (v1)

• Jupiter unauthenticated API — Token2022 and pump.fun tokens may not work.
• No best-price routing — takes whatever Jupiter returns.
• Receipt amounts are best-effort (derived from pre/post balance diffs).
• Solana mainnet only.