@wundercorp/argent

@wundercorp/argent is an open-source CLI for testing MPP machine-payment flows locally.

It is built for teams shipping paid agent endpoints. It checks discovery documents, finds MPP endpoints, verifies the unpaid 402 Payment Required flow, optionally tests a paid or internally verified flow, and can export a Postman collection.

Every run starts with a 3D ASCII startup test that spells out argent.sh.

Install

npm install -g @wundercorp/argent

Global install gives you these commands:

argent
wundercorp-argent
mpp-test
argent-mpp

You can also run it without installing:

npx @wundercorp/argent https://api.wundership.com --endpoint /mpp/plan

During local development:

git clone https://github.com/wundercorp/argent.git
cd argent
npm install
npm link

Quick start

argent https://api.wundership.com

Explicitly test one endpoint:

argent https://api.wundership.com --endpoint /mpp/plan

Use the short alias:

mpp-test https://api.wundership.com --endpoint /mpp/plan

What the CLI tests

The CLI runs these checks:

1. Fetches common agent and MPP discovery documents.
2. Extracts paid endpoints from JSON manifests, OpenAPI paths, llms.txt, and agent cards.
3. Sends an unpaid request to each endpoint.
4. Expects 402 Payment Required by default.
5. Checks for payment challenge evidence in headers or response body.
6. Optionally sends a paid or verified request using payment headers.
7. Optionally writes a Postman collection.

Discovery URLs currently checked:

/llms.txt
/.well-known/mpp.json
/machine-payments.json
/.well-known/agent-card.json
/openapi.json
/openapi-agent.json
/agent-products.json
/agents

Unpaid 402 test

argent https://api.wundership.com \
  --endpoint /mpp/plan \
  --body '{"prompt":"Build a booking app for mobile mechanics"}'

Expected result:

PASS unpaid /mpp/plan status=402 expected=402

A 402 is a successful result for the unpaid public path. It proves agents, Postman, curl, and local smoke tests can reach the endpoint and receive a machine-readable payment challenge.

Paid or verified-flow test

For Wundership-style local verification headers:

MPP_PAYMENT_SECRET=your-secret \
argent https://api.wundership.com \
  --endpoint /mpp/plan \
  --paid

That sends these default headers when MPP_PAYMENT_SECRET is present:

X-Wundership-Agent-Payment-Verified: true
X-Wundership-Agent-Payment-Secret: <secret>
X-Wundership-Agent-Payment-Receipt: argent-<timestamp>

Expected result:

PASS paid /mpp/plan status=200 expected=200

You can also pass custom paid headers for other services:

argent https://api.example.com \
  --endpoint /mpp/plan \
  --paid-header "Authorization: Bearer test-token" \
  --paid-header "X-MPP-Receipt: local-test-001" \
  --paid

Custom body

Inline JSON:

argent https://api.wundership.com \
  --endpoint /mpp/plan \
  --body '{"prompt":"Create an implementation plan for a marketplace"}'

Body file:

argent https://api.wundership.com \
  --endpoint /mpp/plan \
  --body-file ./examples/wundership-body.json

Postman export

argent https://api.wundership.com \
  --endpoint /mpp/plan \
  --postman ./wundership-mpp.postman_collection.json

The generated collection includes both:

Unpaid challenge POST /mpp/plan
Paid verified POST /mpp/plan

Import the collection into Postman and add the paid verification values as needed.

JSON output for CI

argent https://api.wundership.com --endpoint /mpp/plan --json

The process exits with code 0 when the smoke test passes and 1 when it fails.

CLI reference

Usage:
  argent <base-url> [options]
  wundercorp-argent <base-url> [options]
  mpp-test <base-url> [options]
  argent-mpp <base-url> [options]

Core options:
  --endpoint <path-or-url>             Test one endpoint. Repeatable. If omitted, endpoints are discovered.
  --method <method>                    Request method for flow tests. Default: POST.
  --body <json>                        JSON request body. Default is a safe generic prompt payload.
  --body-file <path>                   Read request body from a file.
  --header "Name: value"               Extra header for all requests. Repeatable.
  --timeout <ms>                       Request timeout. Default: 15000.
  --expect-unpaid-status <status>      Expected status for unpaid flow. Default: 402.
  --fail-fast                          Stop at the first failed check.
  --max-endpoints <number>             Maximum discovered endpoints to test. Default: 25.

Paid or verified-flow options:
  --paid                               Also run a paid/verified smoke test.
  --payment-secret <secret>            Secret value for default verified test headers.
  --payment-secret-env <name>          Env var used for the secret. Default: MPP_PAYMENT_SECRET.
  --paid-header "Name: value"          Custom paid-flow header. Repeatable.
  --expect-paid-status <status>        Expected status for paid flow. Default: 200.

Output options:
  --postman <path>                     Write a Postman collection for the tested endpoints.
  --json                               Print machine-readable JSON and suppress the banner.
  --no-banner                          Suppress the argent.sh 3D startup banner.
  --no-color                           Disable ANSI color.
  --verbose                            Print response snippets and discovery details.
  --dry-run                            Discover and render checks without sending endpoint POSTs.
  --version                            Print package version.
  --help                               Print this help text.

Recommended CI smoke test

name: MPP smoke test

on:
  workflow_dispatch:
  schedule:
    - cron: "0 * * * *"

jobs:
  mpp-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx @wundercorp/argent https://api.wundership.com --endpoint /mpp/plan --json

Publishing to npm

Before publishing:

npm test
npm run pack:check
npm login
npm publish --access public

The package is already configured as:

{
  "name": "@wundercorp/argent"
}

Design goals

• No runtime dependencies.
• Works from curl-like local environments, CI, and Postman workflows.
• Defaults to MPP's public 402 challenge semantics.
• Supports Wundership verified headers out of the box.
• Allows generic custom paid headers for other MPP services.
• Useful for humans and agents.

License

MIT