solana-agent-kit-plugin-groundtruth

Solana Agent Kit plugin for GROUNDTRUTH — the recorded outcomes of memecoin launches on Solana (pump.fun) and Robinhood Chain, and the track record of the wallets that launch them.

It gives an agent three things to ask before it buys:

| action | what it answers | endpoint | |---|---|---| | GROUNDTRUTH_CREATOR_RECORD_ACTION | How many coins has this wallet launched, and how many rugged, died, survived or graduated? | /v1/flag | | GROUNDTRUTH_CA_RECORD_ACTION | What is the record on this coin (contract address)? | /v1/record | | GROUNDTRUTH_FLAG_ACTION | Is this creator known bad — does it rug more often than the chain baseline by more than chance? | /api/flag |

These are records, not safety ratings. The plugin never calls a coin or a creator "safe", and known_bad: null means "not in the published set" — absence is not innocence.

Install

npm install solana-agent-kit-plugin-groundtruth

The latest main also installs straight from GitHub (npm install github:groundtruth-now/solana-agent-kit-plugin-groundtruth); it builds on install and exports the same thing.

For x402 pay-per-call, also install the optional peers:

npm install @x402/fetch @x402/core @x402/svm @solana/kit @scure/base

Use

import { SolanaAgentKit } from "solana-agent-kit";
import GroundtruthPlugin from "solana-agent-kit-plugin-groundtruth";

const agent = new SolanaAgentKit(wallet, RPC_URL, {
  GROUNDTRUTH_API_KEY: process.env.GROUNDTRUTH_API_KEY,   // keyed mode, or ...
  // SVM_PRIVATE_KEY: process.env.SVM_PRIVATE_KEY,        // ... x402 mode
}).use(GroundtruthPlugin);

const r = await agent.methods.flag(agent, { address: "WB6dqX3niseHgaMNMiWBkmqQ5heAMGSKxKkdA2WNak3" });

Addresses can be Solana (base58) or Robinhood Chain (0x…); the chain is inferred from the format, or pass chain: "solana" | "rh".

Auth modes

1. GROUNDTRUTH_API_KEY — sent as x-api-key. Get one at groundtruths.xyz.
2. SVM_PRIVATE_KEY (base58) — x402: each paid call costs $0.01 in USDC, paid from the agent's own Solana wallet.
3. Neither — the free trial. When it runs out, calls return { paymentRequired: true } rather than throwing.

x402 safety

A 402 challenge is untrusted input: whoever answers it names the wallet and the amount. The plugin's payment policy signs only when every one of these holds, and otherwise makes no payment at all:

• Solana mainnet, USDC (EPjFWdd5…Dt1v)
• pay-to is GROUNDTRUTH's own wallet, pinned in the plugin (cpCDBTac…ayTP), not taken from the challenge
• the fee payer is the facilitator's published fee payer (pinned) — never the agent's own wallet
• the amount is at or under GROUNDTRUTH_X402_MAX_ATOMIC (default 10000 = $0.01)

Config

| key | default | | |---|---|---| | GROUNDTRUTH_API_KEY | — | keyed mode | | SVM_PRIVATE_KEY | — | x402 mode | | GROUNDTRUTH_X402_MAX_ATOMIC | 10000 | per-call cap, atomic USDC | | GROUNDTRUTH_X402_FEE_PAYER | PayAI's | only if the facilitator rotates its fee payer | | GROUNDTRUTH_API_URL | https://api.groundtruths.xyz | |

Test

npm test     # plugin shape, the payment policy (incl. spoofed pay-to / fee payer / over-cap), live free calls

MIT © GROUNDTRUTH