tokenized-agents

Files (200)

• .env.local.example
• ci.yml · .github/workflows/
• deploy.yml · .github/workflows/
• secret-scan.yml · .github/workflows/
• .gitignore
• .oxfmtrc.jsonc
• .oxlintrc.json
• AGENTS.md
• CHANGELOG.md
• CONTRIBUTING.md
• DEPRECATIONS.md
• LICENSE
• README.md
• SKILL.md
• VISION.md
• clawdhub
• clawhub
• convex.json
• api.d.ts · convex/_generated/
• api.js · convex/_generated/
• dataModel.d.ts · convex/_generated/
• server.d.ts · convex/_generated/
• server.js · convex/_generated/
• appMeta.ts · convex/
• auth.config.ts · convex/
• auth.test.ts · convex/
• auth.ts · convex/
• commentModeration.test.ts · convex/
• commentModeration.ts · convex/
• comments.handlers.ts · convex/
• comments.query.test.ts · convex/
• comments.test.ts · convex/
• comments.ts · convex/
• crons.ts · convex/
• devSeed.ts · convex/
• devSeedExtra.ts · convex/
• downloads.test.ts · convex/
• downloads.ts · convex/
• functions.ts · convex/
• githubBackups.test.ts · convex/
• githubBackups.ts · convex/
• githubBackupsNode.ts · convex/
• githubIdentity.ts · convex/
• githubImport.test.ts · convex/
• githubImport.ts · convex/
• githubRestore.ts · convex/
• githubRestoreMutations.ts · convex/
• githubSoulBackups.ts · convex/
• githubSoulBackupsNode.ts · convex/
• http.ts · convex/
• httpApi.handlers.test.ts · convex/
• httpApi.test.ts · convex/
• httpApi.ts · convex/
• httpApiV1.handlers.test.ts · convex/
• httpApiV1.ts · convex/
• shared.ts · convex/httpApiV1/
• skillsV1.ts · convex/httpApiV1/
• soulsV1.ts · convex/httpApiV1/
• starsV1.ts · convex/httpApiV1/
• transfersV1.ts · convex/httpApiV1/
• …and 140 more

SKILL.md (first lines)

## 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 `@pump-fun/agent-payments-sdk`, not internal module paths.

## Supported Currencies

| Currency    | Decimals | Smallest unit example |
| ----------- | -------- | --------------------- |
| USDC        | 6        | `1000000` = 1 USDC    |
| Wrapped SOL | 9        | `1000000000` = 1 SOL  |

## Environment Variables

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

```env
# 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

```bash
npm install @pump-fun/agent-payments-sdk@3.0.2 @solana/web3.js@^1.98.0
```

### Dependency Compatibility — IMPORTANT

`@pump-fun/agent-payments-sdk` 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 `@pump-fun/agent-payments-sdk` declares in its own `package.json` (inspect it via `npm info @pump-fun/agent-payments-sdk 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 `@pump-fun/agent-payments-sdk`.
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.

```typescript
import { PumpAgent } from "@pump-fun/agent-payments-sdk";
import { PublicKey } from "@solana/web3.js";

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

### Constructor

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

| Parameter     | Type                      | Default     | Description                                                   |
| ------------- | ------------------------- | ----------- | ------------------------------------------------------------- |
| `mint`        | `PublicKey`               | —           | The tokenized agent's token mint address                      |
| `environment` | `"mainnet"` \| `"devnet"` | `"mainnet"` | Network environment                                           |
| `connection`  | `Connection` (optional)   | `undefined` | Solana RPC connection (enables RPC fallback for verification) |

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

```typescript
const agent = new PumpAgent(agentMint);
```

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

```typescript
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](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.

From x402agent/NanoSolana, MIT.

More from x402agent/NanoSolana