Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(pumpfun): add MPL-404 planning helpers

ni3ad2c51e4852fc
diff --git a/packages/pumpfun-skills/README.md b/packages/pumpfun-skills/README.md
index a89573a04..bed9a1da7 100644
--- a/packages/pumpfun-skills/README.md
+++ b/packages/pumpfun-skills/README.md
@@ -4,7 +4,7 @@
<h1 align="center">@three-ws/pumpfun-skills</h1>
-<p align="center"><strong>pump.fun launch + trade as composable agent tools: create a coin, swap, and read creator fees, with a runtime-supplied mint.</strong></p>
+<p align="center"><strong>pump.fun launch, trade, creator fees, and MPL-404 hybrid planning as composable agent tools.</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/pumpfun-skills"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/pumpfun-skills?logo=npm&color=cb3837"></a>
@@ -54,6 +54,8 @@ the user to sign. These skills collapse that into three calls:
`collectFees({...})` builds the claim or distribution transaction.
- **Mint supplied at runtime.** Pass any pump.fun mint you control. There is no
coin list, no allowlist: generic plumbing, your inputs.
+- **MPL-404-ready.** Turn a Pump.fun mint into the fungible backing side of a
+ Metaplex Hybrid V1 project, without pretending Pump.fun itself creates NFTs.
This is the SDK twin of the `pumpfun_create_coin`, `pumpfun_swap`, and
`pumpfun_collect_fees` MCP/skill tools: same endpoints, plain functions.
@@ -128,6 +130,33 @@ the functions below; plus the `AGENT_API_BASE`, `COINS_V2_BASE`, and
`FEE_DESTINATIONS` constants and the `ThreeWsError` / `PaymentRequiredError`
error classes.
+### `createMpl404Plan(input) → Mpl404Plan`
+
+Creates a validated plan for the maintained Metaplex Hybrid program (commonly
+called MPL-404/SPL-404). A Pump.fun launch supplies the fungible SPL mint; a
+Metaplex **Core** collection supplies the NFT side. The helper never sends a
+transaction or holds a secret key. It returns the exact V1 setup parameters for
+your wallet-controlled `initEscrowV1`, followed by `captureV1` and `releaseV1`.
+
+```js
+import { createMpl404Plan } from '@three-ws/pumpfun-skills';
+
+const plan = createMpl404Plan({
+ tokenMint: launch.mint, // Pump.fun mint
+ collection: coreCollection,
+ authority: wallet.publicKey.toBase58(),
+ name: '$THREE relics',
+ uri: 'https://ipfs.io/ipfs/Qm…/hybrid.json',
+ amount: '1000000', // backing token's smallest units per NFT
+});
+// Use plan.initEscrowV1 with @metaplex-foundation/mpl-hybrid's V1 instruction.
+```
+
+Only Core collections are supported by the upstream hybrid program today;
+Token Metadata/pNFT and Token-2022-extension assets must be rejected rather
+than silently producing an unusable escrow. Protocol fees are governed by the
+deployed program, so confirm the current fee in the wallet flow before signing.
+
### `createCoin(input) → Promise<BuiltTx & { mint: string }>`
Build a new-coin transaction with an optional initial buy. The mint keypair is
diff --git a/packages/pumpfun-skills/package.json b/packages/pumpfun-skills/package.json
index 00a026d33..9820ba916 100644
--- a/packages/pumpfun-skills/package.json
+++ b/packages/pumpfun-skills/package.json
@@ -1,6 +1,6 @@
{
"name": "@three-ws/pumpfun-skills",
- "version": "0.1.2",
+ "version": "0.1.3",
"description": "pump.fun launch + trade skills as composable agent tools. Create a coin, swap on the bonding curve or AMM, and read creator fees, with a runtime-supplied mint.",
"type": "module",
"main": "./src/index.js",
diff --git a/packages/pumpfun-skills/src/index.d.ts b/packages/pumpfun-skills/src/index.d.ts
index a45f8be48..9e3ae8e12 100644
--- a/packages/pumpfun-skills/src/index.d.ts
+++ b/packages/pumpfun-skills/src/index.d.ts
@@ -18,6 +18,11 @@ export declare const AGENT_API_BASE: string;
export declare const COINS_V2_BASE: string;
export declare const NATIVE_MINT: string;
export declare const FEE_DESTINATIONS: FeeDestination[];
+/** Metaplex's maintained MPL-404 / hybrid swap program. */
+export declare const MPL_HYBRID_PROGRAM_ID: string;
+export declare const MPL_HYBRID_INSTRUCTION_VERSION: 'V1';
+export declare const MPL_HYBRID_ASSET_STANDARD: 'metaplex-core';
+export declare const MPL_HYBRID_DOCS_URL: string;
export type FeeDestination = 'creator' | 'cashback' | 'sharing_config';
export type SharingConfigMode = 'create' | 'update';
@@ -160,6 +165,45 @@ export interface PumpfunSkillsClient {
coinFees(mint: string, opts?: ReadOptions): Promise<FeeInfo>;
}
+export interface Mpl404PlanInput {
+ /** The Pump.fun (or another SPL Token) mint that backs each hybrid asset. */
+ tokenMint: string;
+ /** Metaplex Core collection address. Token Metadata/pNFT collections are not supported by MPL-Hybrid. */
+ collection: string;
+ /** Wallet that administers the V1 escrow. */
+ authority: string;
+ /** Fee recipient; defaults to authority. */
+ feeLocation?: string;
+ name: string;
+ uri: string;
+ /** Smallest fungible units required to release one Core NFT. */
+ amount: string | number | bigint;
+ min?: string | number | bigint;
+ max?: string | number | bigint;
+ feeAmount?: string | number | bigint;
+ solFeeAmount?: string | number | bigint;
+ path?: number;
+}
+
+export interface Mpl404Plan {
+ standard: 'mpl-404';
+ instructionVersion: 'V1';
+ programId: string;
+ assetStandard: 'metaplex-core';
+ backing: { kind: 'spl-fungible-token'; mint: string };
+ collection: string;
+ authority: string;
+ feeLocation: string;
+ initEscrowV1: Record<string, string | number>;
+ feeNotice: string;
+ docsUrl: string;
+ requiredTransactions: ['initEscrowV1', 'captureV1', 'releaseV1'];
+}
+
+/** Create a validated, user-signed V1 MPL-404 escrow plan for a Pump.fun mint. */
+export declare function createMpl404Plan(input: Mpl404PlanInput): Mpl404Plan;
+export declare function isMpl404Compatible(input: { tokenMint?: string; assetStandard?: string }): boolean;
+
export declare function createPumpfunSkills(options?: PumpfunSkillsOptions): PumpfunSkillsClient;
export declare function createCoin(input: CreateCoinInput, opts?: RequestOptions): Promise<CreateCoinResult>;
export declare function swap(input: SwapInput, opts?: RequestOptions): Promise<BuiltTx>;
diff --git a/packages/pumpfun-skills/src/index.js b/packages/pumpfun-skills/src/index.js
index 92ebc0d21..31c9d6d87 100644
--- a/packages/pumpfun-skills/src/index.js
+++ b/packages/pumpfun-skills/src/index.js
@@ -7,6 +7,15 @@
import { createHttp, ThreeWsError } from './http.js';
+export {
+ MPL_HYBRID_PROGRAM_ID,
+ MPL_HYBRID_INSTRUCTION_VERSION,
+ MPL_HYBRID_ASSET_STANDARD,
+ MPL_HYBRID_DOCS_URL,
+ createMpl404Plan,
+ isMpl404Compatible,
+} from './mpl404.js';
+
export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';
/** pump.fun's agent transaction API: builds the unsigned/mint-signed tx. */
diff --git a/packages/pumpfun-skills/src/mpl404.js b/packages/pumpfun-skills/src/mpl404.js
new file mode 100644
index 000000000..bad7aa718
--- /dev/null
+++ b/packages/pumpfun-skills/src/mpl404.js
@@ -0,0 +1,103 @@
+// MPL-404 (often called SPL-404) planning helpers for Pump.fun mints.
+//
+// Pump.fun creates the fungible side of a hybrid. The maintained hybrid
+// program then escrows that SPL mint against Metaplex Core NFTs. It is not a
+// different Pump.fun launch mode and must never be represented as one: a
+// project needs both a real SPL mint and a Core collection before it can swap.
+
+export const MPL_HYBRID_PROGRAM_ID = 'MPL4o4wMzndgh8T1NVDxELQCj5UQfYTYEkabX3wNKtb';
+export const MPL_HYBRID_INSTRUCTION_VERSION = 'V1';
+export const MPL_HYBRID_ASSET_STANDARD = 'metaplex-core';
+export const MPL_HYBRID_DOCS_URL = 'https://www.metaplex.com/docs/smart-contracts/mpl-hybrid';
+
+const PUBKEY = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+function inputError(message) {
+ const err = new Error(message);
+ err.code = 'invalid_hybrid_input';
+ return err;
+}
+
+function publicKey(value, label) {
+ if (typeof value !== 'string' || !PUBKEY.test(value)) {
+ throw inputError(`${label} must be a base58 Solana public key`);
+ }
+ return value;
+}
+
+function uint(value, label, { min = 0n, max = (1n << 64n) - 1n } = {}) {
+ let parsed;
+ try {
+ parsed = typeof value === 'bigint' ? value : BigInt(value);
+ } catch {
+ throw inputError(`${label} must be an unsigned integer`);
+ }
+ if (parsed < min || parsed > max) throw inputError(`${label} is out of range`);
+ return parsed;
+}
+
+/**
+ * Validate and describe the V1 MPL-Hybrid setup that makes a Pump.fun mint a
+ * hybrid backing token. This function deliberately does not broadcast or
+ * custody a key: callers use the returned values to build the upstream V1
+ * `initEscrowV1` transaction with their own wallet signer.
+ *
+ * `amount` is the number of smallest fungible units required to release one
+ * Core asset. `min` and `max` are passed through to the upstream V1 escrow
+ * instruction and are constrained around that amount to avoid an accidental,
+ * surprising exchange configuration.
+ */
+export function createMpl404Plan(input = {}) {
+ const tokenMint = publicKey(input.tokenMint, 'tokenMint');
+ const collection = publicKey(input.collection, 'collection');
+ const authority = publicKey(input.authority, 'authority');
+ const feeLocation = publicKey(input.feeLocation || authority, 'feeLocation');
+ const amount = uint(input.amount, 'amount', { min: 1n });
+ const min = uint(input.min ?? amount, 'min');
+ const max = uint(input.max ?? amount, 'max');
+ const feeAmount = uint(input.feeAmount ?? 0, 'feeAmount');
+ const solFeeAmount = uint(input.solFeeAmount ?? 0, 'solFeeAmount');
+ const path = uint(input.path ?? 0, 'path', { max: 65535n });
+ const name = String(input.name || '').trim();
+ const uri = String(input.uri || '').trim();
+
+ if (!name || name.length > 32) throw inputError('name must be 1-32 characters');
+ if (!/^https?:\/\//.test(uri) || uri.length > 200) {
+ throw inputError('uri must be an https metadata URL no longer than 200 characters');
+ }
+ if (min > amount || amount > max) {
+ throw inputError('min <= amount <= max is required for a predictable swap ratio');
+ }
+
+ return Object.freeze({
+ standard: 'mpl-404',
+ instructionVersion: MPL_HYBRID_INSTRUCTION_VERSION,
+ programId: MPL_HYBRID_PROGRAM_ID,
+ assetStandard: MPL_HYBRID_ASSET_STANDARD,
+ backing: { kind: 'spl-fungible-token', mint: tokenMint },
+ collection,
+ authority,
+ feeLocation,
+ initEscrowV1: {
+ name,
+ uri,
+ max: max.toString(),
+ min: min.toString(),
+ amount: amount.toString(),
+ feeAmount: feeAmount.toString(),
+ solFeeAmount: solFeeAmount.toString(),
+ path: Number(path),
+ },
+ // Swap protocol fees are controlled by the deployed program. Do not bake a
+ // stale fee number into a product quote; fetch/confirm it at signing time.
+ feeNotice: 'MPL-Hybrid protocol fees may apply. Confirm the current fee before signing.',
+ docsUrl: MPL_HYBRID_DOCS_URL,
+ requiredTransactions: ['initEscrowV1', 'captureV1', 'releaseV1'],
+ });
+}
+
+/** True only for the supported, production-compatible pairing. */
+export function isMpl404Compatible(input = {}) {
+ return input.assetStandard === MPL_HYBRID_ASSET_STANDARD &&
+ typeof input.tokenMint === 'string' && PUBKEY.test(input.tokenMint);
+}
diff --git a/packages/pumpfun-skills/test/pumpfun-skills.test.js b/packages/pumpfun-skills/test/pumpfun-skills.test.js
index b4471f974..83fbd4fd5 100644
--- a/packages/pumpfun-skills/test/pumpfun-skills.test.js
+++ b/packages/pumpfun-skills/test/pumpfun-skills.test.js
@@ -5,6 +5,9 @@ import {
NATIVE_MINT,
ThreeWsError,
PaymentRequiredError,
+ createMpl404Plan,
+ isMpl404Compatible,
+ MPL_HYBRID_PROGRAM_ID,
} from '../src/index.js';
// $THREE is the only coin. Tests use the real $THREE mint or a clearly-synthetic
@@ -13,6 +16,35 @@ const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const SYNTH_MINT = 'THREEsynthetic1111111111111111111111111111';
const WALLET = 'YourWa11et1111111111111111111111111111111111';
+test('createMpl404Plan() makes Pump.fun the SPL backing asset, not a fake launch mode', () => {
+ const plan = createMpl404Plan({
+ tokenMint: THREE_MINT,
+ collection: 'Co11ection111111111111111111111111111111111',
+ authority: WALLET,
+ name: 'THREE relics',
+ uri: 'https://example.com/relics.json',
+ amount: '1000000',
+ });
+ assert.equal(plan.programId, MPL_HYBRID_PROGRAM_ID);
+ assert.equal(plan.assetStandard, 'metaplex-core');
+ assert.equal(plan.backing.mint, THREE_MINT);
+ assert.deepEqual(plan.requiredTransactions, ['initEscrowV1', 'captureV1', 'releaseV1']);
+ assert.equal(plan.initEscrowV1.amount, '1000000');
+ assert.equal(isMpl404Compatible({ tokenMint: THREE_MINT, assetStandard: 'metaplex-core' }), true);
+});
+
+test('createMpl404Plan() rejects an unsafe or inverted swap ratio', () => {
+ assert.throws(() => createMpl404Plan({
+ tokenMint: THREE_MINT, collection: 'bad', authority: WALLET,
+ name: 'x', uri: 'https://example.com/x.json', amount: '1',
+ }), /collection must be a base58/);
+ assert.throws(() => createMpl404Plan({
+ tokenMint: THREE_MINT,
+ collection: 'Co11ection111111111111111111111111111111111', authority: WALLET,
+ name: 'x', uri: 'https://example.com/x.json', min: '2', amount: '1', max: '3',
+ }), /min <= amount <= max/);
+});
+
// A scripted fetch double: each call shifts the next queued response and records
// the request. No network, no real endpoints, we assert on request shaping and
// response parsing, which is all the SDK is responsible for.