@nirholas/agent-payments-sdk

Overview

Cross-chain payments SDK for Pump tokenized agents. The Solana surface ships two coexisting clients — the modern 3.0.x pump_agent_payments program (src/solana/) and a vendored 1.0.7 client for coins registered via @pump-fun/pump-sdk's isTokenizedAgent: true path (src/solana/legacy-agent-payments/). The EVM surface covers payment acceptance and cross-chain quoting on six EVM chains plus an x402 HTTP 402 client/facilitator. Embedded agent skills under swap/, create-coin/, coin-fees/, and tokenized-agents/ ship runnable Node scripts that the parent agent can drive directly.

Install

This package is not published to the npm registry; npm i @nirholas/agent-payments-sdk resolves to a 404. Install it from the GitHub repository instead. Solana is the primary surface and pulls in Anchor and @solana/web3.js; EVM uses viem.

npm i github:nirholas/agent-payments-sdk

Or clone and link it for local development:

git clone https://github.com/nirholas/agent-payments-sdk
cd agent-payments-sdk && npm ci && npm run build

Runtime requirements (from package.json):

Dependency	Version
`@coral-xyz/anchor`	`^0.31.1`
`@solana/web3.js`	`^1.98.0`
`@solana/spl-token`	`^0.4.9`
`viem`	`^2.21.0`
`zod` (peer, optional)	`^3.0.0`

package.json declares "engines": { "node": ">=18" }. Node 18+ is required because the package is ESM-first and the SDK depends on @solana/web3.js@^1.98.

Quickstart: Solana modern (3.0.x)

PumpAgentOffline builds raw TransactionInstructions with no RPC dependency; PumpAgent extends it with balance fetches and other read-only helpers. Verify imports against src/solana/index.ts.

import { Connection, PublicKey } from "@solana/web3.js";
import {
  PumpAgent,
  PumpAgentOffline,
  PUMP_AGENT_PAYMENTS_PROGRAM_ID,
} from "@nirholas/agent-payments-sdk/solana";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const mint = new PublicKey("YourCoinMint1111111111111111111111111111111");

// Connection-bound: fetch balances for a currency vault triplet.
const agent = new PumpAgent(mint, "mainnet", connection);
const balances = await agent.getBalances(
  new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC
);

// Offline-only: register a tokenized agent (returns the unsigned ix).
const offline = PumpAgentOffline.load(mint);
const createIx = await offline.create({
  authority: new PublicKey("BondingCurveCreator11111111111111111111111"),
  mint,
  agentAuthority: new PublicKey("AgentAuthority1111111111111111111111111111"),
  buybackBps: 500,
});

Quickstart: Solana legacy (1.0.7)

The legacy program at pUmPFn9WvfaN2WTVGnCEtJTd2ATTpvpsKRz6jVzu6u4 is a separate on-chain deployment with disjoint PDAs. Use it when:

The coin's tokenized-agent record was created via @pump-fun/pump-sdk@1.35.0's isTokenizedAgent: true flag — that path targets the legacy program.
Downstream tooling has hardcoded the 1.0.7 program ID.

Public-API import path is the namespaced re-export from src/solana/index.ts:

import { PublicKey } from "@solana/web3.js";
import { legacyAgentPayments } from "@nirholas/agent-payments-sdk/solana";

const { LegacyPumpAgentOffline } = legacyAgentPayments;
const mint = new PublicKey("YourCoinMint1111111111111111111111111111111");
const offline = LegacyPumpAgentOffline.load(mint);

const createIx = await offline.create({
  authority: new PublicKey("BondingCurveCreator11111111111111111111111"),
  mint,
  agentAuthority: new PublicKey("AgentAuthority1111111111111111111111111111"),
  buybackBps: 500,
});

The legacy module is also exported under the legacyAgentPayments namespace from the package root and from src/solana/legacy-agent-payments/index.ts. Full reference: docs/legacy-agent-payments.md.

Quickstart: EVM

EvmAgentOffline builds unsigned EVM transactions; EvmAgent adds RPC reads. Exports come from src/evm/index.ts.

No AgentPayments contract is deployed on any of the six chains yet. Every entry in EVM_CHAINS carries agentPayments: 0x0000...0000. The constructors therefore require an explicit contract address and throw a descriptive error without one, rather than building an approve(0x0, maxUint256) and a payment call to the zero address. Check with isAgentPaymentsDeployed(chainId) before assuming a chain is usable.

buildAcceptPaymentTx takes the parameters and the payer as two separate arguments, and returns a bundle of { approval?, tx }. The currency field is named currencyToken and accepts "native" for ETH/BNB/AVAX.

import {
  EvmAgent,
  EvmAgentOffline,
  buildInvoiceWindow,
  isAgentPaymentsDeployed,
} from "@nirholas/agent-payments-sdk/evm";

const AGENT_TOKEN = "0xYourAgentToken00000000000000000000000000";
const AGENT_PAYMENTS = "0xYourDeployedAgentPayments00000000000000";

const offline = new EvmAgentOffline(AGENT_TOKEN, 8453 /* Base */, AGENT_PAYMENTS);

const window = buildInvoiceWindow(600); // 10-minute validity
const bundle = offline.buildAcceptPaymentTx(
  {
    agentToken: AGENT_TOKEN,
    currencyToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
    amount: 1_000_000n,
    memo: 1n,
    startTime: window.startTime,
    endTime: window.endTime,
  },
  "0xPayer000000000000000000000000000000000000",
);

// Send bundle.approval first (ERC-20 only), then bundle.tx.
if (bundle.approval) await wallet.sendTransaction(bundle.approval);
await wallet.sendTransaction(bundle.tx);

const agent = new EvmAgent(AGENT_TOKEN, 8453, undefined /* default RPC */, AGENT_PAYMENTS);
const config = await agent.getAgentConfig();

Public exports map

Subpath	Description
`@nirholas/agent-payments-sdk`	Re-exports the Solana and EVM surfaces; namespaced as `solana`, `evm`, `x402Evm`. Also exports `CrossChainPaymentClient` for EVM to Solana cross-chain flows. See src/index.ts.
`@nirholas/agent-payments-sdk/solana`	`PumpAgent`, `PumpAgentOffline`, PDAs, decoders, events, the `legacyAgentPayments` namespace, and the `x402` namespace. See src/solana/index.ts.
`@nirholas/agent-payments-sdk/evm`	`EvmAgent`, `EvmAgentOffline`, ABIs, chain registry, invoice helpers, event parser. See src/evm/index.ts.
`@nirholas/agent-payments-sdk/x402`	`createEvmX402Fetch` client and EVM facilitator. See src/x402/index.ts.
`@nirholas/agent-payments-sdk/solana/legacy-agent-payments`	`LegacyPumpAgent`, `LegacyPumpAgentOffline`, legacy PDAs and program ID. See src/solana/legacy-agent-payments/index.ts.
`@nirholas/agent-payments-sdk/solana/solana-agent-kit`	`PumpAgentPaymentsPlugin` for solana-agent-kit. See src/solana/solana-agent-kit/.
`@nirholas/agent-payments-sdk/solana-agent-kit`	Alias of the above, kept for existing importers.

The legacy 1.0.7 client is reachable two ways: through the legacyAgentPayments namespace exported from /solana, or through its own ./solana/legacy-agent-payments subpath. Each subpath above also has an /index alias in package.json's exports field.

Skills

Each skill folder contains a SKILL.md plus a scripts/ directory of runnable Node CLI scripts. The skills are designed to be loaded as Claude Code skills.

Skill	Purpose
swap/SKILL.md	Buy/sell on the bonding curve (legacy, v2 and v3 paths) and AMM (v1 and v2), multi-hop swaps across curves and pools, balance prints.
create-coin/SKILL.md	Create coins with optional initial buy, holder rewards, configurable creator fee, mayhem mode, and tokenized-agent registration.
coin-fees/SKILL.md	Inspect, collect, and distribute creator fees (sweeping held v3 / AMM v2 fees first); manage sharing configs.
tokenized-agents/SKILL.md	Build and verify agent invoice payments using this SDK.

vendor/

The vendor/ tree contains reference copies of upstream dependencies. None of them ship in the published dist/ or are wired into the build. The cross-version tests diff this SDK against the published 1.0.7 build, installed as the @pump-fun/agent-payments-sdk-legacy npm alias devDependency (npm:@pump-fun/agent-payments-sdk@1.0.7) so the pin cannot collide with the copy @pump-fun/pump-sdk 4.x pulls in transitively.

Path	What it is
vendor/pump-rust-client/	Rust client crate for the pump program; canonical reference for v2 instruction wiring.
vendor/pump-sdk-npm/	Decompiled `@pump-fun/pump-sdk` source (1.35.x), kept as a historical reference. The runtime dependency is `@pump-fun/pump-sdk` ^4.0.0.
vendor/pump-swap-sdk-npm/	Decompiled `@pump-fun/pump-swap-sdk` for AMM helpers.
vendor/agent-payments-sdk-npm/	The 1.0.7 npm bundle the legacy module was reconstructed from.
vendor/agent-payments-sdk-107/	Unpacked copy of the same 1.0.7 build, kept for reading; the tests use the npm alias above.
vendor/pump-segments-sdk/	Pump segments SDK reference.
vendor/transfer-hook-authority/	Reference source for the transfer-hook authority program.

Build / test / contribute

This package builds with tsup to a dual ESM+CJS dist. Scripts from package.json:

npm ci                 # install from the committed package-lock.json
npm run build          # tsup, dual ESM + CJS into dist/
npm run build:prod     # tsup --minify
npm run typecheck      # tsc --noEmit
npm test               # vitest run
npm run test:watch     # vitest
npm run test:coverage  # vitest run --coverage
npm run clean          # rm -rf dist

Tests run on vitest and live next to the sources they cover (src/**/*.test.ts), plus src/solana/legacy-agent-payments/__tests__/. Coverage is scoped to the legacy module per vitest.config.ts.

The package is ESM-first ("type": "module") and Node 18+ is required for the global fetch and BigInt APIs assumed by the EVM surface.

License

Documentation

Full documentation site: https://nirholas.github.io/agent-payments-sdk/

Getting started covers install and first run.
Examples has copy-paste snippets.

Star History

Support the project

If agent-payments-sdk saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/agent-payments-sdk and it has the context it needs.

More from the same author

All repositories by nirholas: the full catalog, grouped by topic
three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
Questions or ideas: open an issue or start a discussion

Navigation Menu

Repository navigation

About

Repository files navigation

@nirholas/agent-payments-sdk

Overview

Install

Quickstart: Solana modern (3.0.x)

Quickstart: Solana legacy (1.0.7)

Quickstart: EVM

Public exports map

Skills

vendor/

Build / test / contribute

License

Documentation

Star History

Support the project

Built for AI agents too

More from the same author

Contributors

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
agent-prompts		agent-prompts
coin-fees		coin-fees
create-coin		create-coin
create-usdc-coin		create-usdc-coin
docs		docs
pump-public-docs		pump-public-docs
scripts		scripts
src		src
swap		swap
tokenized-agents		tokenized-agents
vendor		vendor
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
llms-full.txt		llms-full.txt
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

@nirholas/agent-payments-sdk

Overview

Install

Quickstart: Solana modern (3.0.x)

Quickstart: Solana legacy (1.0.7)

Quickstart: EVM

Public exports map

Skills

vendor/

Build / test / contribute

License

Documentation

Star History

Support the project

Built for AI agents too

More from the same author

Contributors

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages