Skip to main content

mpp-make-payments

Example payment client — pays for an MPP-gated resource the way an autonomous agent would, with safe retries that reuse the same signed credential.
This walks through an example client that behaves like an agent: it requests an MPP-gated resource, receives a 402 with an atum-escrow challenge, and pays for it automatically with no human in the loop.
The client holds its own signing key, so it pays as the participant that key belongs to. That is how the 402 flow works — it checks the signature, not who is behind the software. Establishing who is answerable when software spends for someone else is Know Your Agent, a separate question.

​
Prerequisites

npm is included with Node.js.
Verify:
Your agent needs a wallet that holds the source token on the chain the merchant accepts.Export its private key — use a testnet-only wallet, never one holding real funds. See Set up a testnet wallet.Against the merchant’s default stub submitter no real transaction is submitted, so any private key works for a local run.
For real settlement, the Permit2 contract must be approved to spend your source token. The client can do this for you: set RPC_URL in .env and it approves the token before paying, via the ensureSourceApproval helper.Skip this step when running against the stub merchant — no on-chain approval is needed.

​
Prerequisites for real settlement

Local stub runs need no funds. Before you point the client at testnet or mainnet, confirm your payer wallet has the source token, native gas for the one-time Permit2 approve(), and an active allowance — see Prerequisites.

​
1. Clone and install

​
2. Configure

Set PRIVATE_KEY in .env to your agent wallet’s 0x-prefixed key — it’s the only value you need to run against the local stub merchant. The client’s other variables (MERCHANT_URL, RPC_URL) are documented in the example README; the corridor itself is the merchant’s config, not the client’s.
Switching wallets, environments, or corridors? If you exported PRIVATE_KEY in your shell earlier (export PRIVATE_KEY=0x…), that value overrides .env — dotenv does not replace variables already set in your environment, so the client can silently sign with the wrong wallet after you edit .env. Run unset PRIVATE_KEY before npm run pay so the value from .env is used.

​
3. Start the merchant (if running locally)

Follow Agentic receives to start the merchant server first:
The merchant is a separate app, so it needs its own npm install (the clone step only installed mpp-make-payments). To install all four example apps at once instead, run npm run install:all from the repo root.
Its default stub submitter needs no gateway and no funds.

​
4. Run the client

Back in mpp-make-payments:
Expected output:

​
What’s happening

Looking at src/client.ts and src/purchase.ts:
  1. registerClient teaches the mppx client how to build and sign an atum-escrow credential; the source account is derived from your key.
  2. The client requests the resource under a purchase identifier in the URL (/paid/<purchase id>), reads the 402 atum-escrow challenge (which carries that id as intentId), and signs a Permit2 authorization over the source token.
  3. It retries with that credential in an Authorization: Payment header.
  4. If settlement is still pending, it re-attempts the same purchase: fresh 402, newly signed credential, same purchase id. The gateway resolves onto the original payment — see Idempotency and src/purchase.ts.
The wallet signs a Permit2 authorization — it does not broadcast a transaction. The deposit only executes on-chain when the merchant settles through Atum’s Payment Gateway. MPP has no facilitator — the merchant verifies and settles via the non-custodial Atum Payment Gateway (see the overview).

​
Going to testnet or mainnet

Real settlement means funding your agent’s wallet, approving the source token (Permit2), and pointing MERCHANT_URL at a merchant that settles through a live Atum Payment Gateway. See the example README for .env values, funding amounts, and on-chain verification — its Going to testnet or mainnet section walks through that app. New to Atum’s environments? See Choose an environment for which one to target and what to expect from production-testnet. Run through the pre-flight checklist before your first real payment.

​
Next steps