# Getting started \[The mppx TypeScript library] ## Overview The `mppx` TypeScript library provides a typed interface over the Machine Payments Protocol, from high-level abstractions to low-level primitives and building blocks.
## Install :::code-group ```bash [npm] npm install mppx ``` ```bash [pnpm] pnpm add mppx ``` ```bash [bun] bun add mppx ``` ::: ## Quick start This quick start guide shows you how to use `mppx` with the [`tempo` payment method](/payment-methods/tempo). You can apply the same patterns to [other payment methods](/payment-methods).
::::steps #### Install peer dependencies In this example, you use the `viem` library to instantiate an account. :::code-group ```bash [npm] npm install viem ``` ```bash [pnpm] pnpm add viem ``` ```bash [bun] bun add viem ``` ::: #### Define an account Next, define an account to sign payments. ```ts twoslash [define-account.ts] import { privateKeyToAccount } from 'viem/accounts' const account = privateKeyToAccount('0xabc…123') ``` :::tip When using Tempo, you can also use [Passkey or WebCrypto accounts](https://viem.sh/tempo/accounts). ::: #### Create payment handler Call `Mppx.create` at startup. This polyfills the global `fetch` to automatically handle `402` payment challenges. ```ts twoslash [create-paid-fetch.ts] import { privateKeyToAccount } from 'viem/accounts' import { Mppx, tempo } from 'mppx/client' // [!code hl] const account = privateKeyToAccount('0xabc…123') Mppx.create({ // [!code hl] methods: [tempo({ account })], // [!code hl] }) // [!code hl] ``` :::tip If you want to avoid polyfilling, use the returned `fetch` instead. ```ts const mppx = Mppx.create({ polyfill: false, // [!code hl] methods: [tempo({ account })] }) const response = await mppx.fetch('https://mpp.dev/api/ping/paid') // [!code hl] ``` ::: #### Request protected resources Use `fetch`. Payment happens when a server returns `402`. ```ts twoslash [fetch-resource.ts] const response = await fetch('https://mpp.dev/api/ping/paid') ``` ::::
#### Framework mode Use the framework-specific middleware from `mppx` to integrate payment into your server. Each middleware handles the `402` challenge/credential flow and attaches receipts automatically. ::::code-group ```ts [Next.js] import { Mppx, tempo } from 'mppx/nextjs' // [!code hl:start] const mppx = Mppx.create({ methods: [tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', })], }) // [!code hl:end] export const GET = mppx.charge({ amount: '0.1' }) // [!code hl] (() => Response.json({ data: '...' })) ``` ```ts [Hono] import { Hono } from 'hono' import { Mppx, tempo } from 'mppx/hono' const app = new Hono() // [!code hl:start] const mppx = Mppx.create({ methods: [tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', })], }) // [!code hl:end] app.get( '/resource', mppx.charge({ amount: '0.1' }), // [!code hl] (c) => c.json({ data: '...' }), ) ``` ```ts [Elysia] import { Elysia } from 'elysia' import { Mppx, tempo } from 'mppx/elysia' // [!code hl:start] const mppx = Mppx.create({ methods: [tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', })], }) // [!code hl:end] const app = new Elysia() .guard( { beforeHandle: mppx.charge({ amount: '0.1' }) }, // [!code hl] (app) => app.get('/resource', () => ({ data: '...' })), ) ``` ```ts [Express] import express from 'express' import { Mppx, tempo } from 'mppx/express' const app = express() // [!code hl:start] const mppx = Mppx.create({ methods: [tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', })], }) // [!code hl:end] app.get( '/resource', mppx.charge({ amount: '0.1' }), // [!code hl] (req, res) => res.json({ data: '...' })) ``` :::: :::tip You can also override `currency` and `recipient` per call if different routes need different payment configurations. ```ts mppx.charge({ amount: '0.1', currency: '0x…', // [!code ++] recipient: '0x…', // [!code ++] }) ``` ::: :::note Don't see your framework? `mppx` is designed to be framework-agnostic. See [Manual mode](#manual-mode) below. :::
***
#### Manual mode If you prefer full control over the payment flow, use `mppx/server` directly with the Fetch API. ```ts twoslash import { Mppx, tempo } from 'mppx/server' const mppx = Mppx.create({ methods: [tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', })], }) // [!code focus:start] export async function handler(request: Request) { const response = await mppx.charge({ amount: '0.1' })(request) // [!code focus:end] // Payment required: send 402 response with challenge if (response.status === 402) return response.challenge // Payment verified: attach receipt and return resource return response.withReceipt(Response.json({ data: '...' })) } ``` :::info\[Currency and recipient values] `currency` is the TIP-20 token contract address—`0x20c0…` is PathUSD on Tempo. `recipient` is the address that receives payment. See [Tempo payment method](/payment-methods/tempo) for supported tokens. ::: The intent handler accepts a [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-compatible request object, and returns a `Response` object. The Fetch API is compatible with most server frameworks, including: [Hono](https://hono.dev), [Deno](https://deno.com), [Cloudflare Workers](https://workers.dev), [Next.js](https://nextjs.org), [Bun](https://bun.sh), and other Fetch API-compatible frameworks. :::tip You can also override `currency` and `recipient` per call if different routes need different payment configurations. ```ts const response = await mppx.charge({ amount: '0.1', currency: '0x…', // [!code ++] recipient: '0x…', // [!code ++] })(request) ``` :::
***
## Node.js & Express compatibility If your framework doesn't support the **Fetch API** (for example, Express or Node.js), you're likely interfacing with the [Node.js Request Listener API](https://nodejs.org/api/http.html#httpcreateserveroptions-requestlistener). Use the `Mppx.toNodeListener` helper to transform the handler into a Node.js-compatible listener. ```ts twoslash import { Mppx, tempo } from 'mppx/server' const mppx = Mppx.create({ methods: [tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', })], }) type IncomingMessage = import('node:http').IncomingMessage type ServerResponse = import('node:http').ServerResponse // ---cut--- export async function handler(req: IncomingMessage, res: ServerResponse) { const response = await Mppx.toNodeListener( // [!code ++] mppx.charge({ amount: '0.1' }) )(req, res) // [!code ++] // Payment required: send 402 response with challenge if (response.status === 402) return response.challenge // Payment verified: attach receipt and return resource return response.withReceipt(Response.json({ data: '...' })) } ```
The `mppx` package install automatically includes a [CLI tool](/sdk/typescript/cli) you can use to make the same request from the command line. ::::steps #### Create an account Create a Tempo account to sign payments. The account is auto-funded on testnet and key is stored in your system keychain. :::code-group ```bash [npm] $ npx mppx account create ``` ```bash [pnpm] $ pnpm mppx account create ``` ```bash [bun] $ bunx mppx account create ``` ::: #### Make a paid request Run the CLI with a URL to make a paid request. Payment is handled automatically when the server returns `402`. :::code-group ```bash [npm] $ npx mppx https://mpp.dev/api/ping/paid ``` ```bash [pnpm] $ pnpm mppx https://mpp.dev/api/ping/paid ``` ```bash [bun] $ bunx mppx https://mpp.dev/api/ping/paid ``` ::: ::::