Tokenized Agents

Before Starting Work

MANDATORY — Do NOT write or modify any code until every item below is answered by the user:

• Agent token mint address (from pump.fun)
• Payment currency decided (USDC or SOL)
• Price/amount confirmed (in smallest unit)
• RPC URL provided or a fallback agreed upon
• Framework confirmed (Next.js, Express, other)

You MUST ask the user for ALL unchecked items in your very first response. Do not assume defaults. Do not proceed until the user has explicitly answered each one.

Safety Rules

• NEVER log, print, or return private keys or secret key material.
• NEVER sign transactions on behalf of a user — you build the instruction, the user signs.
• Always validate that amount > 0 before creating an invoice.
• Always ensure endTime > startTime and both are valid Unix timestamps.
• Use the correct decimal precision for the currency (6 decimals for USDC, 9 for SOL).
• Always verify payments on the server using validateInvoicePayment before delivering any service. Never trust the client alone — clients can be spoofed.
• Always verify your code against this skill before finalizing. Before delivering generated code, re-read the relevant sections of this document and confirm:
  • Parameter types match the documented signatures — buildAcceptPaymentInstructions accepts number for numeric fields, validateInvoicePayment accepts number, and getInvoiceIdPDA accepts number.
  • Parameter ordering and names match exactly.
  • Default values (e.g. computeUnitLimit defaults to 100_000) are not contradicted.
  • Import paths use @three-ws/agent-payments, not internal module paths.

Supported Currencies

Environment Variables

Create a .env (or .env.local for Next.js) file with the following:

# Solana RPC — server-side (used to build transactions and verify payments)
SOLANA_RPC_URL=https://rpc.solanatracker.io/public

# Solana RPC — client-side (used by wallet adapter in the browser)
NEXT_PUBLIC_SOLANA_RPC_URL=https://rpc.solanatracker.io/public

# The token mint address of your tokenized agent on pump.fun
AGENT_TOKEN_MINT_ADDRESS=<your-agent-mint-address>

# Payment currency mint
# USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# SOL (wrapped): So11111111111111111111111111111111111111112
CURRENCY_MINT=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

RPC for mainnet-beta: The default Solana public RPC (https://api.mainnet-beta.solana.com) does not support sending transactions. You MUST ask the user which RPC endpoint to use. Present these free mainnet-beta options if the user does not have their own:

• Solana Tracker — https://rpc.solanatracker.io/public
• Ankr — https://rpc.ankr.com/solana

Do NOT silently pick one — wait for the user to confirm before proceeding.

Read these values from process.env at runtime. Never hard-code mint addresses or RPC URLs.

Install

npm install @three-ws/agent-payments @solana/web3.js@^1.98.0

Dependency Compatibility — IMPORTANT

@three-ws/agent-payments depends on @solana/web3.js and @solana/spl-token. When the app also installs these packages directly, mismatched versions can cause runtime errors.

Rules:

1. Before installing @solana/web3.js, @solana/spl-token, or any @solana/wallet-adapter-* package, first check what versions @three-ws/agent-payments declares in its own package.json (inspect it via npm info @three-ws/agent-payments dependencies). Install the same ranges — or ranges that resolve to the same major.minor — so npm/pnpm hoists a single copy instead of two.
2. Never blindly install "latest" for these shared packages. Always prefer the version that is most compatible with the latest @three-ws/agent-payments.
3. If the project already has these packages at different versions, align them to match the SDK and re-install.

SDK Setup

PumpAgent is the main class. It can build payment instructions and verify invoices.

import { PumpAgent } from "@three-ws/agent-payments";
import { PublicKey } from "@solana/web3.js";

const agentMint = new PublicKey(process.env.AGENT_TOKEN_MINT_ADDRESS!);

Constructor

new PumpAgent(mint: PublicKey, environment?: "mainnet" | "devnet", connection?: Connection)

Without connection — enough for building instructions and HTTP-based payment verification:

const agent = new PumpAgent(agentMint);

With connection — also enables RPC-based verification fallback and balance queries:

import { Connection } from "@solana/web3.js";

const connection = new Connection(process.env.SOLANA_RPC_URL!);
const agent = new PumpAgent(agentMint, "mainnet", connection);

Wallet Integration (Frontend)

Install @solana/wallet-adapter-react, @solana/wallet-adapter-react-ui, and @solana/wallet-adapter-wallets. Use useWallet() for publicKey and signTransaction, and useConnection() for the active RPC connection. MUST See https://raw.githubusercontent.com/pump-fun/pump-fun-skills/refs/heads/main/tokenized-agents/references/WALLET_INTEGRATION.md for the full WalletProvider setup, layout wrapping, and hook usage.

Building Payment Instructions

Use buildAcceptPaymentInstructions to get all the instructions needed for a payment. This is the recommended method — it automatically derives the user's token account and handles native SOL wrapping/unwrapping.

Parameters (BuildAcceptPaymentParams)

Example

const ixs = await agent.buildAcceptPaymentInstructions({
  user: userPublicKey,
  currencyMint,
  amount: "1000000", // 1 USDC
  memo: "123456789", // unique invoice identifier
  startTime: "1700000000", // valid from
  endTime: "1700086400", // expires at
});

What It Returns

The returned TransactionInstruction[] always starts with compute budget instructions, followed by the payment instructions:

• SetComputeUnitLimit is always prepended (default 100_000 CU). Override via computeUnitLimit if your transactions fail with "compute exceeded".
• SetComputeUnitPrice is prepended only when computeUnitPrice is provided. Use this to set a priority fee for faster landing during congestion.

After the compute budget prefix:

• For SPL tokens (USDC): The accept-payment instruction.
• For native SOL: Instructions that handle wrapping/unwrapping automatically:
  1. Create the user's wrapped SOL token account (idempotent)
  2. Transfer SOL lamports into that token account
  3. Sync the native balance
  4. The accept-payment instruction
  5. Close the wrapped SOL account (returns rent back to user)

You do not need to handle SOL wrapping or compute budget yourself — buildAcceptPaymentInstructions does it for you.

Important

• The amount, memo, startTime, and endTime must exactly match when verifying later.
• Each unique combination of (mint, currencyMint, amount, memo, startTime, endTime) can only be paid once — the on-chain Invoice ID PDA prevents duplicate payments.
• Generate a unique memo for each invoice (e.g. Math.floor(Math.random() * 900000000000) + 100000).

Deriving the Invoice ID

The Invoice ID is a PDA (PublicKey) that uniquely identifies an invoice on-chain. It is derived deterministically from the six invoice parameters. Both buildAcceptPaymentInstructions and validateInvoicePayment derive it internally, but you can also compute it yourself.

Import

import { getInvoiceIdPDA } from "@three-ws/agent-payments";
import { PublicKey } from "@solana/web3.js";

Usage

getInvoiceIdPDA returns [PublicKey, number]. The first element is the Invoice ID; the second is the PDA bump seed.

const tokenMint = new PublicKey(process.env.AGENT_TOKEN_MINT_ADDRESS!);
const currencyMint = new PublicKey(process.env.CURRENCY_MINT!);

const amount = 1000000;
const memo = 123456789;
const startTime = 1700000000;
const endTime = 1700086400;

const [invoiceId] = getInvoiceIdPDA(
  tokenMint,
  currencyMint,
  amount,
  memo,
  startTime,
  endTime,
);

console.log("Invoice ID:", invoiceId.toBase58());

All numeric parameters (amount, memo, startTime, endTime) are plain number values. BN conversion is handled internally.