Back to documentation

Postman Collection

Test the x402 BSV payment gateway with this complete Postman collection. Covers both Profile A (demo mode) and Profile B (template settlement) flows.

x402-gateway-postman-collection.json

Import into Postman

1

Download the collection

Click the download button above to save the JSON file.

2

Open Postman

Launch the Postman desktop app or open the web version.

3

Import the collection

Click Import (top-left), then drag and drop the JSON file. The collection appears in your sidebar.

4

Configure variables

Click the collection name, go to the Variables tab, and update gatewayUrl / delegatorUrl if your server runs on different ports.

What's Included

The collection is organized into folders covering both settlement profiles and all gateway endpoints.

Profile A — Demo Mode Flow
Manual and automatic x402 flows using the mock broadcaster. No BSV crypto needed. Ideal for development and testing.
Profile B — Template Settlement
Full 6-step production flow: challenge, decode, delegate, broadcast, build proof, access resource. Client-orchestrated with pre-signed templates.
Health & Status
Gateway and delegator health check endpoints for monitoring service availability.
Delegator API
Fee delegation endpoints, UTXO stats, and health checks for the delegator service.
Dashboard API
Configuration, statistics, treasury management, and UTXO monitoring endpoints.

Collection Variables

These variables are pre-configured with defaults. Update them to match your deployment.

VariableDefaultDescription
gatewayUrl http://localhost:8402 x402 gateway base URL
delegatorUrl http://localhost:8403 Fee delegator base URL
broadcastUrl https://api.whatsonchain.com/v1/bsv/main/tx/raw WhatsOnChain broadcast endpoint (Profile B)
arcUrl https://arc.gorillapool.io/v1 GorillaPool ARC base URL

Profile A — Demo Mode

The simplest way to test the x402 protocol. The gateway handles proof-building server-side via POST /demo/build-proof.

Prerequisites

Flow

  1. GET /v1/expensive → 402 + X402-Challenge header
  2. POST /demo/build-proof → server builds proof
  3. GET /v1/expensive + X402-Proof header → 200 OK
  4. Replay same proof → 409 double_spend (replay protection)

Profile B — Template Settlement

Production flow where the gateway pre-signs a transaction template. The client orchestrates the settlement through the delegator.

Prerequisites

6-Step Flow

  1. GET /v1/expensive → 402 + X402-Challenge (contains template)
  2. Decode challenge → extract template.rawtx_hex
  3. POST /delegate/x402 with partial_tx → completed_tx + txid
  4. POST broadcastUrl with txhex → broadcast to BSV network
  5. Build X402-Proof header from completed_tx + challenge binding
  6. GET /v1/expensive with X402-Proof → 200 OK

All Postman test scripts include automated assertions and console logging at every step.

Run with Newman (CLI)

You can also run the collection from the command line using Newman.

npm install -g newman
newman run x402-gateway-postman-collection.json