Solana Payment Evidence Skill

A Solana AI Kit skill for verifying payment evidence, reconciling invoices, and preventing false "revenue received" labels.

This skill helps agents prove whether a SOL or SPL-token payment actually settled to the expected recipient, for the expected mint and amount, at the required commitment level. It is built for founders, operators, bounty hunters, grant recipients, and autonomous agents that need durable payment proof instead of screenshots or vague wallet callbacks.

Why This Exists

Solana builders already have strong tools for sending payments. The recurring gap is after the send:

• Did the payment reach the right recipient?
• Was it the right mint, not a fake symbol?
• Was the amount exact enough for the invoice?
• Is the transaction finalized or only processed?
• Can this be safely marked as real revenue?

This skill gives agents a strict verification workflow and a no-dependency Python helper for checking direct SOL and SPL-token transfers through Solana RPC.

What's Included

solana-payment-evidence-skill/
  README.md
  LICENSE
  install.sh
  install.ps1
  bounty-submission.md
  skill/
    SKILL.md
    references/
      evidence-pack.md
      payment-requests.md
      reconciliation.md
      revenue-labels.md
      verify-payment.md
    scripts/
      make_payment_request.py
      verify_solana_payment.py
    agents/
      openai.yaml
  examples/
    sol-payment.evidence.json
    usdc-payment.evidence.json
  tests/
    fixtures/
    test_verify_solana_payment.py

Install

Claude/Codex Skill Folder

git clone https://github.com/ideals2201/solana-payment-evidence-skill.git
cd solana-payment-evidence-skill
./install.sh

The installer copies skill/ to:

~/.claude/skills/solana-payment-evidence

On Windows PowerShell:

.\install.ps1

Quick Verification

Run an offline fixture:

python skill/scripts/verify_solana_payment.py examples/usdc-payment.evidence.json \
  --transaction-json tests/fixtures/usdc-transfer.tx.json \
  --format text

Expected result:

Label: settled
Reason: expected transfer matched

Run tests with the Python standard library:

python -m unittest discover -s tests -q

Live RPC Usage

Create an evidence JSON with a real signature:

{
  "cluster": "mainnet-beta",
  "signature": "REAL_SIGNATURE",
  "recipient": "RECIPIENT_WALLET",
  "asset": {
    "type": "spl",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "symbol": "USDC",
    "decimals": 6
  },
  "amount": "25.00",
  "commitment": "finalized",
  "reference": "invoice-2026-001"
}

Then run:

python skill/scripts/verify_solana_payment.py payment.evidence.json

The script exits:

• 0 for settled
• 1 for pending or mismatched evidence
• 2 for malformed input or verification errors

Supported

• Native SOL recipient balance deltas.
• SPL token recipient owner/mint balance deltas.
• Decimal or atomic amount comparison.
• Optional exact match and tolerance.
• Optional reference/memo/account-key check.
• Online RPC verification and offline fixture verification.

Not Yet Supported

• Swap output attribution across multiple token routes.
• Escrow or multisig program state verification.
• Compressed tokens or non-standard token programs.
• Partial payments across multiple signatures.

The skill routes these to unsupported_complex_flow instead of pretending they are settled.

Bounty Fit

This is a new cross-domain skill for the Solana AI Kit. It combines Solana RPC verification, founder revenue operations, bounty/grant payout evidence, and agent-safe accounting language.

Closest existing material: payment UX guidance in Solana/game/payment skills and Commerce Kit documentation. This repo focuses on the missing back-office proof layer: how to verify, label, and reconcile money after a transaction is claimed.

License

MIT. See LICENSE.