@mpp32/sdk
v0.2.0
Published
SDK for the MPP32 Machine-Payable API Platform — Solana token intelligence with x402 USDC on Solana and Base, plus Tempo pathUSD
Maintainers
Readme
mpp32
TypeScript SDK for MPP32 — the universal payment proxy for machine-payable APIs. Handles the full HTTP 402 payment flow so your agent can call paid APIs with one function call.
Install
npm install @mpp32/sdkPayment dependencies
The signing libraries are optional — free-tier and read-only calls
(listServices, agent-key'd analyze) need none of them. Install only the peer
dependencies for the protocol you actually pay with. If they are missing when a
payment is attempted, the SDK throws a clear error naming the exact package to
install (it never silently sends a broken or unsigned envelope):
# x402 USDC on Base (EVM key)
npm install viem
# Tempo pathUSD (same EVM key)
npm install mppx viem
# x402 USDC on Solana (Solana key), requires Node 20.18+
npm install @solana/kit @solana-program/token @solana-program/compute-budget @scure/baseEnvironment variables
The client reads these when the matching config option is not passed. The
names match the mpp32-mcp-server package.
| Variable | Config option | Purpose |
|---|---|---|
| MPP32_AGENT_KEY | agentKey | Free tier, dashboard tracking, spend limits. Sent only to the MPP32 API origin. |
| MPP32_PRIVATE_KEY | evmPrivateKey | ONE EVM key (hex) that pays both x402 USDC on Base and Tempo pathUSD. |
| MPP32_SOLANA_PRIVATE_KEY | solanaPrivateKey | Solana key (base58, JSON byte array, or hex) for x402 USDC on Solana. |
| MPP32_PREFERRED_NETWORK | preferredNetwork | solana, base, evm, tempo, or a CAIP-2 id: which rail to try first. Without it the order is Base, then Solana, then Tempo. |
| MPP32_MAX_PRICE_USD | maxPriceUsd | Refuse to sign any single payment above this USD amount. |
| MPP32_SOLANA_RPC_URL | solanaRpcUrl | Solana RPC used to fetch a blockhash when signing. |
| MPP32_API_URL | apiUrl | API base URL (default https://mpp32.org). |
Keys never leave the process. Only signatures are sent.
Free tier / no wallet
You can construct the client with just an agent key (no private key) to use the
free tier, dashboard usage tracking, and listServices:
const client = new MPP32({ agentKey: process.env.MPP32_AGENT_KEY })Quick Start
import { MPP32 } from '@mpp32/sdk'
// Reads MPP32_AGENT_KEY, MPP32_PRIVATE_KEY and MPP32_SOLANA_PRIVATE_KEY from
// the environment. Pass them explicitly to override.
const client = new MPP32({
// evmPrivateKey: process.env.MPP32_PRIVATE_KEY,
// solanaPrivateKey: process.env.MPP32_SOLANA_PRIVATE_KEY,
})
// Get Solana token intelligence
const intel = await client.analyze('SOL')
console.log(intel.alphaScore, intel.rugRisk.level)
// List all available services
const services = await client.listServices()
// Call any registered service
const result = await client.callService('some-service-slug', {
method: 'POST',
body: JSON.stringify({ query: 'example' }),
})Configuration
const client = new MPP32({
agentKey: 'mpp32_agent_...', // or MPP32_AGENT_KEY
evmPrivateKey: '0x...', // or MPP32_PRIVATE_KEY: x402 on Base + Tempo
solanaPrivateKey: '[...]', // or MPP32_SOLANA_PRIVATE_KEY: x402 on Solana
preferredMethod: 'auto', // 'tempo' | 'x402' | 'auto'
preferredNetwork: 'base', // or MPP32_PREFERRED_NETWORK
maxPriceUsd: 0.5, // or MPP32_MAX_PRICE_USD
apiUrl: 'https://mpp32.org', // Override API base URL
retry: true, // Enable retry with exponential backoff
headers: { 'X-Custom': 'val' }, // Default headers for all requests
})tempoPrivateKey is still accepted as a deprecated alias for evmPrivateKey.
No key is required to construct the client. Free-tier and read-only calls work with just an agentKey (or nothing). A private key is only required when a real 402 challenge must be signed. With preferredMethod: 'auto' (the default) the SDK tries every rail you hold a key for — x402 USDC on Base, then x402 USDC on Solana, then Tempo pathUSD — and if the server rejects one payment (for example, an empty wallet on that chain) it moves on to the next. Nothing is ever retried unpaid, and a rejected payment is not charged.
How payments work
- What gets signed. Only the x402
exactscheme on Solana mainnet (solana,solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) and Base mainnet (base,eip155:8453), plus Tempo pathUSD. Other offers (testnets, other chains, other schemes) are skipped. If nothing offered is payable with your keys, the SDK throws an error listing what the server offered and which key would enable payment. It never retries without paying. - Where the challenge is read from. The x402 v2
PAYMENT-REQUIREDheader, the x402 v1 JSON body of the 402, orWWW-Authenticate: Payment(Tempo). Through/api/agent/execute, the same data is read from the wrappedresult.error.challenge. - Wire format. v2 payments are sent in
PAYMENT-SIGNATUREas{ x402Version: 2, resource, accepted, payload }, whereacceptedis the chosenacceptsentry, unmodified. v1 payments are sent inX-PAYMENTas{ x402Version: 1, scheme, network, payload }. Only one of the two headers is ever sent. Tempo goes inAuthorization. - After paying. If the paid retry comes back as another 402, the SDK throws
MPP32: payment rejected: <reason>. Settlement details are in the response'sPAYMENT-RESPONSE/X-PAYMENT-RESPONSEheader;parseX402SettlementHeaderdecodes it.
API
client.analyze(token: string)
Returns intelligence data for a Solana token: alpha score, rug risk, whale activity, smart money signals, market data, and more. With an agent key this calls POST /api/agent/execute with { service: "intelligence", method: "POST", body: { token } }, so the daily free tier, dashboard tracking and your spend limits apply. After the free tier runs out, the SDK pays the wrapped 402 with your wallet key. Without an agent key it calls /api/intelligence directly and pays the 402.
client.listServices(category?: string)
Lists all approved services on MPP32. Optionally filter by category.
client.callService(slug, options?)
Calls any registered service through the MPP32 proxy. Handles 402 payment automatically.
client.paidFetch(url, init?)
Low-level method. Works like fetch(), but answers an HTTP 402 by signing one payment and retrying once. It works with any x402 or Tempo endpoint, not only MPP32. The agent key and X-MPP32-Client header are only attached to requests to the MPP32 API origin.
x402 helpers
parseX402Challenge, selectX402Offer, buildX402PaymentHeader, signX402Payment, parseX402SettlementHeader and extractPaymentRejectionReason are exported for custom clients.
Runtime
No Buffer or node:crypto is used: base64 goes through atob/btoa, and nonces come from crypto.getRandomValues, so the core works in browsers and edge runtimes. Solana signing still needs Node 20.18+ (or an equivalent WebCrypto Ed25519 implementation).
License
MIT
