POMP developer docs

You need an AO signer, the Module/Authority/Scheduler for the process home (Forward or arweave.nyc), the matching write URL, Arweave artwork, and a full Spawn → Eval → Setup. Missing any of these breaks create/claim or keeps the POMP hidden from Discover.

• Signer: Wander, PermawebOS, MetaMask (ETH type-3), Phantom (Solana type-4), or your own key via @permaweb/aoconnect. XRP is not supported — an XRP-only wallet cannot sign ANS-104.
• Artwork: POMP-Artwork must be a 43-char Arweave tx id. IPFS → fetch → upload to Arweave first (optional POMP-Artwork-IPFS for provenance).
• Lifecycle: Spawn → Eval campaign Lua → Setup-POMP-Campaign. Incomplete setup stays hidden from public Discover. Optional POMP-Client for attribution.
• Create fee: may apply on PermaTell’s create UI after a free quota. Partner SDK spawns do not use the site fee voucher. Claims are never charged.
• Install: npm i @permatell/pomp-sdk@0.1.4 (peer @permaweb/aoconnect only for create/claim). https://www.npmjs.com/package/@permatell/pomp-sdk — v0.1.4 for wallet-free listPomps/getPomp; v0.1.3 for Solana claim wallets; v0.1.2+ for NYC-home routing; v0.1.1+ defaults Forward Scheduler; on 0.1.0 pass scheduler explicitly.

Discover indexes any AO process that carries the right tags. There is no custodial mint API — spawn with documented Module/Scheduler/Authority for that home, Eval campaign Lua, then Setup-POMP-Campaign. Keep App-Name=PermaTell; use POMP-Client for partner attribution.

• App-Name = PermaTell
• POMP-Asset-Type = native-event | poap-claim
• POMP-Source = POMP | POAP

After spawn: Eval campaign Lua → Setup-POMP-Campaign. Incomplete setup stays hidden from public Discover.

Optional: POMP-Client (e.g. xrp-mini-app) and POMP-Client-Version for attribution. Filter Discover with ?client=.

Writes are POST /{id}~process@1.0/push with Content-Type application/ans104 (sync). Ethereum uses MetaMask personal_sign over the ANS-104 deep hash (type 3). Solana uses HexInjectedSolanaSigner on hex(deepHash) (type 4). Stamp PermaTell-Signer-Type ethereum or solana on those DataItems.

Write node follows the process Scheduler/Authority, not whether Forward is down. NYC-home (Scheduler Kfn-GDmC…) sends RSA, ETH, and Solana messages to https://arweave.nyc. Forward-home RSA goes to app-1; ETH/Solana go to schedule.forward.

Never rewrite a Forward-home process onto NYC. Passing writeUrl https://arweave.nyc while Scheduler is still Forward does not move writes — spread NYC_CONNECT (SDK 0.1.2+) or pass the NYC Scheduler.

The PermaTell app (PR #128) defaults RSA, ETH (MetaMask type-3), and Solana (Phantom type-4) new creates to arweave.nyc; Forward is backup only when NYC is down. The SDK does not auto-route from node health — spread NYC_CONNECT or pass Scheduler Kfn-GDmCtv1cjMp4qFdZlg6VmzeMex6SM1HpVj1q_Vg for NYC-home. Existing Forward POMPs stay on their scheduler. If spawn HTTP 200 + valid id, continue Eval/Setup. Solana spawn may historically HTTP 500 scheduler_timeout for ~10s — do not blindly retry. After a node patch, 500 JSON may include a process field; the app treats 500-with-id as pending and confirms assignment on the same host before Eval. Not all SDK users get that JSON field. If 500/timeout without a process id, do not click Create again — refresh and check Profile / Resume setup. Unique 1/1 mint stays Arweave L1 only (AR fee on token@1.0). NYC-home RSA, ETH type-3, and Solana type-4 claims were proven in the browser on 2026-10-22 (Haunt + a new EVM drop + Phantom create+claim). Haunt-class Lua that omits solana in AddressFormats still replies Invalid claim wallet until creator Eval. XRP is not supported.

import { createPompSdk, NYC_CONNECT } from "@permatell/pomp-sdk";

const sdk = createPompSdk(
  { ...NYC_CONNECT, signerKind: "ethereum", client: "my-app" },
  ethereumDataItemSigner
);

// claimPomp(id, word, { scheduler: "Kfn-GDmCtv1cjMp4qFdZlg6VmzeMex6SM1HpVj1q_Vg" }) from Forward-default SDK

Public NYC-home campaign l-z5Sm48r4IfYu7AS_sKZlbKsSIqyq3JaoaAvCvelTg. NYC-home claims proven in the browser on 2026-10-22: RSA, ETH type-3 (Haunt + a new EVM drop), and Solana type-4 (Phantom create+claim on a new 0.1.3 campaign). Read state from arweave.nyc. Do not post a live claim from this example and do not publish the Haunt claim word. Haunt-class Lua (AddressFormats=arweave,ethereum) still replies Invalid claim wallet for Solana until the creator Evals Lua 0.4.

Public on every PermaTell spawn. SDK 0.1.1+ defaults to the Forward Module / Authority / Scheduler triple. SDK 0.1.2+ / 0.1.3 add NYC_CONNECT for NYC-home. The PermaTell app defaults new creates to NYC (PR #128) — partners matching that must spread NYC_CONNECT. Module is the same on both homes. Keep write URL with the same Scheduler/Authority — never mix Forward Scheduler with arweave.nyc.

• Module (both homes) = ISShJH1ij-hPPt9St5UFFr_8Ys3Kj5cyg7zrMGt7H9s
• Forward Authority = a5ZMUKbGClAsKzB4SHDYrwkOZZHIIfpbaxrmKwUHCe8
• Forward Scheduler = n_XZJhUnmldNFo4dhajoPZWhBXuJk-OcQr5JQ49c4Zo
• Forward RSA write = https://app-1.forward.computer
• Forward ETH/Solana write = https://schedule.forward.computer
• NYC Scheduler/Authority = Kfn-GDmCtv1cjMp4qFdZlg6VmzeMex6SM1HpVj1q_Vg · write/read = https://arweave.nyc

Third-party sites can list and show POMPs without a wallet. listPomps and getPomp wrap the same CORS Discover / asset APIs as permatell.xyz (GraphQL, HyperBEAM hydrate, unindexed NYC stamps). Do not scrape HTML. Unknown-home writes still need Scheduler / NYC_CONNECT; reads still find NYC POMPs when listed via Discover.

import { listPomps, getPomp } from "@permatell/pomp-sdk";

const pomps = await listPomps({ limit: 12 });
const pomp = await getPomp(pomps[0].assetId);
// card: pomp.title, pomp.artworkUrl, pomp.remaining, pomp.claimed,
// pomp.maxClaims, pomp.creator, pomp.hbNode, pomp.claimUrl

npm i @permatell/pomp-sdk@0.1.4

Published as @permatell/pomp-sdk. Peer @permaweb/aoconnect is only required for create/claim. Browser-first — no wallet UI is bundled. Display: listPomps / getPomp (no wallet). Writes: createPomp / claimPomp via createPompSdk + a DataItemSigner. Use 0.1.4+ for wallet-free reads; 0.1.3 for Solana claim wallets in campaign Lua (0.1.2+ for NYC-home routing). Spread NYC_CONNECT so creates match the PermaTell app’s NYC default. Reads still find NYC POMPs via Discover on a Forward-default SDK.

POMP-Artwork must be a 43-character Arweave transaction id. If media is on IPFS, fetch the CID, upload bytes to Arweave, then pass the tx id. Optional POMP-Artwork-IPFS is provenance only.

Prefer SDK listPomps / getPomp (no wallet). GET/OPTIONS CORS is enabled on /api/pomp/discover, /top, /profile, /campaign/[id], and /asset/[id]. HyperBEAM proxy and create-fee routes stay same-origin — call HyperBEAM nodes or GraphQL directly for raw process state.

• GET /api/pomp/discover
• GET /api/pomp/top
• GET /api/pomp/profile?wallet=
• GET /api/pomp/campaign/[id]
• GET /api/pomp/asset/[id]

Anyone who can spawn AO can stamp PermaTell tags. Avoid PermaTell-Test and test title prefixes. Claim words must be ≥6 characters; weak words are discouraged. We may hide abusive process ids. Unique 1/1 minting is optional and is Arweave L1 only (AR fee on token@1.0) — see the EVM guide for caveats.

1. Provide an AO signer (Wander / PermawebOS / MetaMask / Phantom / own key). XRP is not supported — XRP-only is not enough. Phantom claims work on new 0.1.3 campaign Lua; frozen Haunt-class processes still need operator Eval.
2. Fetch IPFS artwork → upload to Arweave → keep the 43-char artworkId.
3. Spawn with the home’s Module/Authority/Scheduler + write URL (SDK 0.1.1+ Forward defaults, or NYC_CONNECT on 0.1.2+ / 0.1.3 to match the app’s NYC create default), then Eval → Setup-POMP-Campaign.
4. Optional POMP-Client; share /pomp/claim/{assetId}; confirm HyperBEAM state and Discover after indexing.

XRP is not supported. XRP-only wallets cannot sign AO/ANS-104 — you need an Arweave/AO signer (Wander, PermawebOS, MetaMask, Phantom, or your own key).