Skip to main content

​
Overview

The protocols supported by mag3nt (MPP, AP2, and x402) all rely on the standard HTTP 402 Payment Required status code, originally defined in HTTP/1.1 (RFC 7231). To negotiate and settle payments over HTTP, these protocols use the standard W3C header format:
  • WWW-Authenticate: Payment: Sent by the server to challenge the client for payment.
  • Authorization: Payment: Sent by the client (agent) as proof of payment to unlock the resource.
This is the transport layer that makes machine-to-machine payments possible.

​
The Challenge (WWW-Authenticate)

When an agent attempts to access a paid resource without valid payment, the server responds with a 402 Payment Required and a challenge header. 
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="chal_123", realm="api.example.com", method="mpp", intent="charge", request="base64url_encoded_payload"

​
Anatomy of a Challenge

ParameterDescription
idA unique identifier for the challenge.
realmThe domain or namespace of the resource.
methodThe accepted payment protocol (e.g., x402, mpp, ap2).
intentTypically charge or authorize.
requestA base64url-encoded payload containing the price, currency, network, and recipient details.
The request payload varies by method. For example, an MPP payload might decode to: 
{
  "amount": 100000,
  "currency": "USDC",
  "recipient": "0xYourAddress",
  "methodDetails": {
    "chainId": 8453
  }
}

​
The Receipt (Authorization)

After the agent’s wallet (or mag3nt’s Universal Payment Engine) settles the payment on-chain, the agent retries the request with an Authorization header containing the cryptographic proof. 
GET /resource HTTP/1.1
Host: api.example.com
Authorization: Payment eyJjaGFsbGVuZ2UiOiB7...
The credential is a base64url-encoded JSON object that echoes the original challenge and includes a payload with the settlement proof (e.g., a transaction hash for Push payments, or a signature for Pull payments). 
{
  "challenge": {
    "id": "chal_123",
    "method": "mpp"
  },
  "payload": {
    "type": "hash",
    "hash": "0xabcd1234..."
  },
  "source": "did:pkh:eip155:8453:0xAgentAddress"
}

​
How mag3nt Handles This

You don’t have to manually parse these headers when making outbound payments. When your agent hits a 402, you pass the target URL to mag3nt’s universal payments.execute endpoint. mag3nt automatically probes the URL, reads the WWW-Authenticate header, decodes the request, executes the on-chain transfer, and returns the signed Authorization: Payment credential for your agent to use.

​
Live Demo

We built a live Adverse Media Screening demo to showcase the standard W3C header-based flow in action: The demo serves as a resource server that protects its screening API with 402 Payment Required headers. You can configure your agent with a mag3nt card, query the screening API, handle the challenge, and unlock the resource. The repository provides a reference implementation for constructing W3C payment challenges and verifying agent payments on-chain.