SDKs — TypeScript and Python

Thin typed clients for the Polypad agent API, version 2.0.0, matching the server. They do not reimplement the API: they call the same MCP endpoint, with typed wrappers for the tools, the prepare → sign → confirm helper, persistent wallet binding, and the x402 payment helper. No signup, no API key, no approval.

Install

The packages are built and tested, but not yet published to npm or PyPI — publishing as polypad-agent is the next step. Until then, install them from the repo: TypeScript with npm install in the ts/ folder, Python with pip install -e py/. Once published, it is npm install polypad-agent and pip install polypad-agent.

Wallet binding: connect once

A prepare call needs to know which wallet will sign. Instead of passing the address on every call, connect once: show the user the connect URL (polypad.family/sign?connect=1 — client.connectUrl() builds it), they connect their wallet and sign one message — not a transaction, no funds move — and get a token. Store it as POLYPAD_WALLET_TOKEN. The client passes it instead of a wallet address; the server recovers the wallet from the signature.

The token lasts 90 days; after that, connect again. It cannot be revoked from the server — it stops working when it expires, or when the holder deletes it — so treat it like a password for that one wallet and never paste it in a public chat. Per-call from still works as the fallback: pass it explicitly and the client leaves the token out for that call. How the token is built and checked is on the sign loop page.

Quickstart — TypeScript

import { PolypadClient } from "polypad-agent";

const client = new PolypadClient(); // reads POLYPAD_WALLET_TOKEN
console.log(await client.listTokens({ sort: "new", limit: 5 }));
console.log(await client.quoteTrade({ token: "POLYDASH", side: "buy", amountEth: "0.01" }));
const mint = await client.prepareFundMint({ fund: "0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", quantity: 1 });
console.log(mint.signing.url); // the user opens this and signs

Quickstart — Python

from polypad_agent import PolypadClient

client = PolypadClient()  # reads POLYPAD_WALLET_TOKEN
print(client.list_tokens(sort="new", limit=5))
print(client.quote_trade(token="POLYDASH", side="buy", amountEth="0.01"))
mint = client.prepare_fund_mint(fund="0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", quantity=1)
print(mint["signing"]["url"])  # the user opens this and signs

The loop: prepare → sign → confirm

An action is not done when it is prepared, and not done when it is signed — it is done when the agent knows the result. The helper has two shapes. For a chat agent, it prepares, hands the signing link to your callback for the user to open, waits for the transaction hash (from the returnUrl callback, or the user pasting it back), then polls polypad_get_tx_status until the chain confirms it. For a script with its own wallet — the Forge path — it prepares, signs and sends each step with the script's own key, waits for each step's receipt before the next, then polls for the final result. The signing key must be the bound wallet — never the Polypad deployer wallet. Python has the same two helpers: prepare_sign_confirm and prepare_sign_broadcast.

// Chat agent: prepare, show the link, wait for the hash, poll until confirmed.
const done = await client.prepareSignConfirm({
  tool: "polypad_prepare_fund_mint",
  arguments: { fund: "0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", quantity: 1 },
  returnUrl: "https://example.com/agent/done",
  onSigningLink: (url, summary) => console.log(summary.headline, url),
  getTxHash: async () => readHashFromReturnCallback(),
});
console.log(done.status, done.txHash, done.result);

// Script with its own wallet (the Forge path): prepare, sign, broadcast, confirm.
const launched = await client.prepareSignBroadcast({
  tool: "polypad_prepare_token_launch",
  arguments: { name: "Agent Swarm", symbol: "SWARM", creatorFeeBps: 100, devBuyEth: "0" },
  privateKey: process.env.LAUNCHER_PRIVATE_KEY,
});
console.log(launched.status, launched.txHash);

Recipes

Two recipes ship with each SDK, both using the bound wallet — no per-call address anywhere:

  • Launch a token from a script (examples/launch-token): prepare the launch, sign and broadcast it, confirm it, then create the token's staking pool by calling the factory directly — there is no MCP tool for staking pools yet. This is the Forge path; the numbers are in the case studies.
  • Run a tokenized fund from an agent (examples/run-fund): create the fund (Strategy #6, the LP-Dividend strategy), then mint the manager's skin shares so the raise can open. Investors then mint through the same prepare → sign → confirm loop.

Pay-per-call (x402)

payForReport / pay_for_report fetches a priced report — token report $0.01, fund NAV $0.01, CTO report $0.05 — paying with USDG (EIP-3009). Ask, get a 402 with the price, sign the authorization, send it back in the X-PAYMENT header. The server only settles after the report is built — if the report cannot be built, nothing is charged.

Every tool, with inputs and copy-paste examples, is in the tool reference, and the limits are on the rules of the road page. Contracts are unaudited.