solana-payments

An agent skill for integrating Solana SPL token payments (USDC/USDT) into any payment system.

Built for AI coding agents (Claude Code, Cursor, Windsurf, Cline, Codex, etc.) that need to implement Solana payment flows.

What It Covers

Topic	Details
Wallet Generation	Ed25519 keypairs, base58 encoding, secure storage
Balance Checking	ATA lookups for USDC + USDT, handling non-existent accounts
Transfer Detection	Signature history, parsed transactions, pre/post balance diffs
Sweep Logic	Master-as-fee-payer pattern (deposit wallet never needs SOL)
Payment Verification	3 approaches: balance query, WebSocket, tx history parsing
Commitment Levels	processed vs confirmed vs finalized with use-case mapping
Transaction Retry	Blockhash management, priority fees, error classification
Security	Mint hardcoding, idempotency, token program validation
Production RPC	Provider comparison (Helius, QuickNode, Triton, Alchemy)
Indexing	Yellowstone gRPC, webhooks, when to scale beyond RPC polling
Devnet Testing	Circle test USDC mint, faucets, testing checklist

Install

Claude Code

claude skill add sepivip/solana-payments-skill

Manual (any agent)

Clone into your agent's skills directory:

# Universal (.agents/skills/)
git clone https://github.com/sepivip/solana-payments-skill.git .agents/skills/solana-payments

# Claude Code
ln -s $(pwd)/.agents/skills/solana-payments .claude/skills/solana-payments

# Cursor
ln -s $(pwd)/.agents/skills/solana-payments .cursor/skills/solana-payments

Key Technical Decisions

Why @solana/web3.js v1? — v2 is a full API rewrite still stabilizing. v1 is battle-tested with comprehensive docs and community support.

Why master-as-fee-payer for sweeps? — Eliminates the SOL funding step entirely. The master wallet pays ~$0.001 per sweep, and deposit wallets never need SOL. Simpler and cheaper than the EVM fund-then-transfer pattern.

Why not Token-2022? — USDC and USDT on Solana both use the original Token Program. Token-2022 is for newer tokens (PYUSD, USDG). Using the wrong program produces invalid ATAs.

Token Addresses

Token	Mint (Mainnet)	Decimals
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB	6

Dependencies

npm install @solana/web3.js@1 @solana/spl-token bs58

Context

Originally built for Toppio — a crypto-to-fiat bridge where users send USDC/USDT and receive mobile top-ups. The skill implements a chain-agnostic PaymentProvider interface that works alongside existing BSC and Polygon providers.

The patterns are general enough to apply to any Solana payment integration.

License

MIT