MPP TestKit

Posted on May 9

A Self-Monetizing API in 20 Lines of Code

This is a hands-on tutorial. By the end you'll have a running pay-per-request API server, a client that pays automatically, and a test suite that covers the full payment flow - all on devnet, completely free.

The Problem With How We Monetize APIs Today

If you've ever tried to sell access to an API you built, you know the drill:

Sign up for Stripe
Build a subscription checkout flow
Issue API keys on payment confirmation
Store keys in a database
Validate keys on every request
Build a usage dashboard
Handle expired cards, failed payments, refunds
Write the billing docs

By the time you've done all that, you've built a billing product. That wasn't the thing you wanted to build.

The worst part: none of this scales to small amounts. Charging $0.001 per API call with Stripe isn't viable - the processing fee alone exceeds the charge. So you're forced into subscriptions, bundles, and credit packs. Your pricing model becomes a product decision instead of just... pricing.

There's a cleaner way to do this. It's been in the HTTP spec since 1999. It just never had the infrastructure to work.

HTTP 402: The Status Code That Was Waiting for Blockchains

402 Payment Required

This status code has been reserved in HTTP since the original 1.1 spec. The idea: server tells the client "pay first, then retry." The client pays, retries with proof, gets the resource.

The problem was always how. How does the server specify the amount? In what form? How does the client pay programmatically? How does the server verify payment without a central authority?

Blockchains answer all of those questions. Solana specifically:

Specifies amount in SOL (or any token)
Accepts payment via a signed transaction
Provides on-chain verification with no intermediary
Confirms transactions in ~2 seconds
Charges fractions of a cent in fees

MPP Testkit is the SDK that wires this up. Let's build something with it.

What We're Building

A Node.js API server with:

/api/ping - free endpoint, no payment
/api/weather - costs 0.001 SOL per call
/api/forecast - costs 0.005 SOL per call (premium tier)

And a client script that:

Hits the paid endpoints automatically
Handles the wallet, airdrop, and payment without any manual steps
Logs every step of the flow

Total code: about 20 lines for the server, 10 for the client.

Setup

mkdir my-paid-api && cd my-paid-api
npm init -y
npm install express mpp-test-sdk

Create two files: server.js and client.js.

The Server

// server.js
import express from "express";
import { createTestServer } from "mpp-test-sdk";

const app = express();
const mpp = createTestServer();

// Free - no payment needed
app.get("/api/ping", (req, res) => {
  res.json({ status: "ok", ts: Date.now() });
});

// 0.001 SOL per call
app.get("/api/weather",
  mpp.charge({ amount: "0.001" }),
  (req, res) => {
    res.json({
      city: "San Francisco",
      temp: 62,
      condition: "Partly cloudy",
      paid: true,
    });
  }
);

// 0.005 SOL per call - premium tier
app.get("/api/forecast",
  mpp.charge({ amount: "0.005" }),
  (req, res) => {
    res.json({
      city: "San Francisco",
      forecast: [
        { day: "Mon", high: 65, low: 54 },
        { day: "Tue", high: 68, low: 57 },
        { day: "Wed", high: 61, low: 52 },
      ],
      model: "v2-premium",
      paid: true,
    });
  }
);

app.listen(3001, () => {
  console.log("Server running on :3001");
  console.log("Payment recipient:", mpp.recipientAddress);
});

Start it:

node server.js
# Server running on :3001
# Payment recipient: 7xKmPq2rNbMd...

That's the server. mpp.charge() is Express middleware. It returns a 402 if no valid payment receipt is present, verifies on-chain if one is, and calls next() if everything checks out.

The Client

// client.js
import { createTestClient } from "mpp-test-sdk";

const client = await createTestClient({
  network: "devnet",
  onStep: ({ type, message }) => console.log(`  [${type}] ${message}`),
});

console.log("\n- Hitting /api/ping (free)");
const ping = await client.fetch("http://localhost:3001/api/ping");
console.log(await ping.json());

console.log("\n- Hitting /api/weather (0.001 SOL)");
const weather = await client.fetch("http://localhost:3001/api/weather");
console.log(await weather.json());

console.log("\n- Hitting /api/forecast (0.005 SOL)");
const forecast = await client.fetch("http://localhost:3001/api/forecast");
console.log(await forecast.json());

Run it:

node client.js

- Hitting /api/ping (free)
{ status: 'ok', ts: 1715123456789 }

- Hitting /api/weather (0.001 SOL)
  [wallet-created] Keypair generated: 3xMn9...Wr4k
  [funded] Airdropped 2 SOL on devnet
  [request] GET http://localhost:3001/api/weather
  [payment] 402 received · paying 0.001 SOL
  [payment] tx confirmed: 5xKm7...Pq2r
  [retry] Retrying with Payment-Receipt header
  [success] 200 OK
{ city: 'San Francisco', temp: 62, condition: 'Partly cloudy', paid: true }

- Hitting /api/forecast (0.005 SOL)
  [request] GET http://localhost:3001/api/forecast
  [payment] 402 received · paying 0.005 SOL
  [payment] tx confirmed: 8xNp3...Qr1s
  [retry] Retrying with Payment-Receipt header
  [success] 200 OK
{ city: 'San Francisco', forecast: [...], model: 'v2-premium', paid: true }

Notice: the wallet and airdrop only happen once. The second paid call reuses the same wallet - no second airdrop. The client is stateful, the calls are not.

What Just Happened Under the Hood

When the client hit /api/weather:

Client sent GET /api/weather - no special headers
Server returned 402 Payment Required with header:

   Payment-Request: solana; amount="0.001"; recipient="7xKmPq2r..."

SDK parsed the header, built a Solana transaction for 0.001 SOL to 7xKmPq2r...
SDK signed and submitted the transaction to devnet
SDK waited for confirmation (~2 seconds)
Client retried with header:

   Payment-Receipt: solana; signature="5xKm7...Pq2r"

Server verified on-chain: transaction exists, recipient matches, amount ≥ 0.001 SOL
Server called next(), handler returned 200

Your handler code saw none of this. It just received a request and returned JSON.

Writing Tests for Your Paid Endpoints

This is where MPP Testkit really shines. Integration testing paid APIs usually means mocking the payment layer, which means your tests don't actually test the payment logic.

With MPP Testkit on devnet, you test the real flow for free:

// server.test.js
import { createTestClient } from "mpp-test-sdk";
import { describe, test, expect, beforeAll, afterAll } from "vitest";

let client;
let server;

beforeAll(async () => {
  // Start the server
  server = await import("./server.js");

  // Create a test client - wallet + airdrop happen here once
  client = await createTestClient({ network: "devnet" });
});

afterAll(() => server.close());

describe("Free endpoints", () => {
  test("GET /api/ping returns 200 without payment", async () => {
    const res = await client.fetch("http://localhost:3001/api/ping");
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body).toHaveProperty("status", "ok");
  });
});

describe("Paid endpoints", () => {
  test("GET /api/weather: pays 0.001 SOL, returns weather data", async () => {
    const res = await client.fetch("http://localhost:3001/api/weather");
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body).toHaveProperty("temp");
    expect(body.paid).toBe(true);
  });

  test("GET /api/forecast: pays 0.005 SOL, returns 3-day forecast", async () => {
    const res = await client.fetch("http://localhost:3001/api/forecast");
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.forecast).toHaveLength(3);
  });

  test("Direct request without payment returns 402", async () => {
    const res = await fetch("http://localhost:3001/api/weather");
    expect(res.status).toBe(402);
    const header = res.headers.get("Payment-Request");
    expect(header).toMatch(/solana/);
    expect(header).toMatch(/amount="0.001"/);
  });

  test("Request with invalid receipt returns 403", async () => {
    const res = await fetch("http://localhost:3001/api/weather", {
      headers: { "Payment-Receipt": "solana; signature=fakesig123" },
    });
    expect(res.status).toBe(403);
  });
});

Run with:

npx vitest

These are real integration tests. No mocks. No stubs. The payment flow runs against devnet on every test run. If your receipt verification logic breaks, the test catches it - because it actually verifies.

Handling Errors Gracefully

Real code needs error handling. The SDK throws typed errors:

import {
  mppFetch,
  MppFaucetError,
  MppPaymentError,
  MppTimeoutError,
} from "mpp-test-sdk";

async function fetchWithFallback(url) {
  try {
    return await mppFetch(url);
  } catch (err) {
    if (err instanceof MppFaucetError) {
      // Devnet faucet rate-limited - common in CI with many parallel runs
      console.warn("Faucet unavailable, retrying in 60s...");
      await sleep(60_000);
      return mppFetch(url); // retry once
    }

    if (err instanceof MppPaymentError) {
      // Transaction rejected - log and rethrow
      console.error(`Payment rejected: ${err.url} → ${err.status}`);
      throw err;
    }

    if (err instanceof MppTimeoutError) {
      // Flow took too long - Solana can be slow under load
      console.error(`Timed out after ${err.timeoutMs}ms`);
      throw err;
    }

    throw err;
  }
}

Taking It to Production (Mainnet)

When you're ready to charge real SOL:

Server side - pin a stable recipient wallet:

const mpp = createTestServer({
  secretKey: process.env.SERVER_SECRET_KEY, // base64 or JSON array
  network: "mainnet",
});

Client side - provide a funded wallet:

const client = await createTestClient({
  network: "mainnet",
  secretKey: process.env.CLIENT_SECRET_KEY, // pre-funded with real SOL
});

The protocol is identical. The only difference is network: "mainnet" and no auto-airdrop. Your application code doesn't change.

The Creator Economy Angle

I want to zoom out for a second, because this is bigger than just APIs.

If you're a developer who creates things - libraries, datasets, AI models, tools - the standard monetization paths are:

Open source - free, you get nothing
SaaS - build a subscription billing system (Stripe, auth, database, dashboard)
One-time license - Gumroad, Paddle, etc. - purchase gate, license key management
Usage-based - Stripe metered billing - still requires subscription, monthly invoicing

All of these require you to build infrastructure around your actual product.

HTTP 402 with Solana adds a fifth option: embed payment in the protocol itself.

Your dataset endpoint charges $0.0001 per query. Your AI model charges $0.01 per inference. Your code analysis tool charges $0.005 per file. No subscription. No free tier decision. No pricing page. The price is in the API response.

Consumers - including AI agents - just pay and use. Your server accumulates SOL. You withdraw to your wallet.

The entire billing system is the blockchain.

Why This Matters for AI Agents Right Now

We're at an inflection point: AI agents are being deployed that autonomously call tools, APIs, and services. The problem is that every one of those tools currently requires a human to sign up, get an API key, and manage billing.

That doesn't scale. An agent that spins up 50 tool-calling sessions needs 50 sets of credentials managed by a human. Or one set of credentials shared across everything - which is a security disaster.

HTTP 402 with Solana gives agents a payment identity without a human in the loop:

Agent generates an ephemeral keypair on first run
Agent funds wallet from its operator's SOL balance
Agent hits any 402-gated endpoint and pays automatically
Operator monitors spending via on-chain transactions

No API keys. No credentials database. No revocation system. The wallet is the identity. The payment is the access token.

The Auton demo shows this working end-to-end - an agent that generates its own wallet, gets funded, navigates a 402 gate, pays, and retrieves premium data. Every step streams live to the browser. Watch it once and the architecture becomes obvious.

Quick Reference

Install

npm install mpp-test-sdk       # TypeScript/JavaScript
pip install mpp-test-sdk       # Python
go get github.com/mpptestkit/mpp-test-sdk-go  # Go

Minimal server

import { createTestServer } from "mpp-test-sdk";
const mpp = createTestServer();
app.get("/paid", mpp.charge({ amount: "0.001" }), handler);

Minimal client

import { mppFetch } from "mpp-test-sdk";
const res = await mppFetch("https://your-api.com/paid");

Networks

Network	Auto-funded	Cost
`devnet`	Yes (2 SOL)	Free
`testnet`	Yes (2 SOL)	Free
`mainnet`	No	Real SOL

Error types

Error	Cause
`MppFaucetError`	Devnet/testnet faucet rate-limited
`MppPaymentError`	On-chain transaction rejected
`MppTimeoutError`	Full flow exceeded timeout
`MppNetworkError`	Mainnet attempted without funded wallet

What's Next

Once you have the basics running:

Add multiple price tiers - mpp.charge({ amount: "0.01" }) on premium endpoints, mpp.charge({ amount: "0.001" }) on standard
Use the lifecycle events - stream payment status to your frontend in real-time (the playground does this)
Integrate with your existing auth - 402 and API keys aren't mutually exclusive; use 402 for metered access, API keys for identity
Move to mainnet - same code, swap network: "devnet" to network: "mainnet", provide funded wallets

The interactive playground is the fastest way to see the full flow before you build anything. It runs against a live server - no setup, no install.

DEV Community