x402 Pay

curl --request POST \
  --url https://api.example.com/v1/x402/pay \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "method": "<string>",
  "headers": {},
  "body": "<string>",
  "max_amount_usdc": 123
}
'

import requests

url = "https://api.example.com/v1/x402/pay"

payload = {
    "url": "<string>",
    "method": "<string>",
    "headers": {},
    "body": "<string>",
    "max_amount_usdc": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: '<string>',
    method: '<string>',
    headers: {},
    body: JSON.stringify('<string>'),
    max_amount_usdc: 123
  })
};

fetch('https://api.example.com/v1/x402/pay', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/x402/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'method' => '<string>',
    'headers' => [
        
    ],
    'body' => '<string>',
    'max_amount_usdc' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/x402/pay"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"method\": \"<string>\",\n  \"headers\": {},\n  \"body\": \"<string>\",\n  \"max_amount_usdc\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/x402/pay")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"method\": \"<string>\",\n  \"headers\": {},\n  \"body\": \"<string>\",\n  \"max_amount_usdc\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/x402/pay")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"method\": \"<string>\",\n  \"headers\": {},\n  \"body\": \"<string>\",\n  \"max_amount_usdc\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "status_code": 123,
  "headers": {},
  "body": "<string>",
  "payment_amount": 123,
  "fee_amount": 123,
  "tx_hash": {},
  "settled": true
}

POST

x402

pay

x402 Pay

curl --request POST \
  --url https://api.example.com/v1/x402/pay \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "method": "<string>",
  "headers": {},
  "body": "<string>",
  "max_amount_usdc": 123
}
'

import requests

url = "https://api.example.com/v1/x402/pay"

payload = {
    "url": "<string>",
    "method": "<string>",
    "headers": {},
    "body": "<string>",
    "max_amount_usdc": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: '<string>',
    method: '<string>',
    headers: {},
    body: JSON.stringify('<string>'),
    max_amount_usdc: 123
  })
};

fetch('https://api.example.com/v1/x402/pay', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/x402/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'method' => '<string>',
    'headers' => [
        
    ],
    'body' => '<string>',
    'max_amount_usdc' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/x402/pay"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"method\": \"<string>\",\n  \"headers\": {},\n  \"body\": \"<string>\",\n  \"max_amount_usdc\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/x402/pay")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"method\": \"<string>\",\n  \"headers\": {},\n  \"body\": \"<string>\",\n  \"max_amount_usdc\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/x402/pay")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"method\": \"<string>\",\n  \"headers\": {},\n  \"body\": \"<string>\",\n  \"max_amount_usdc\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "status_code": 123,
  "headers": {},
  "body": "<string>",
  "payment_amount": 123,
  "fee_amount": 123,
  "tx_hash": {},
  "settled": true
}

This endpoint is deprecated. Use POST /v1/pay with a URL recipient instead.

Proxies an HTTP request to a target API. If the API returns HTTP 402 Payment Required, the backend automatically signs an EIP-3009 USDC authorization, retries the request with the x402 payment header, and returns the API response.

Requires a bearer token with the x402 permission.

Request Body

string

required

Target API URL. Max 2048 characters.

string

default:"GET"

HTTP method for the request. One of GET, POST, PUT, DELETE.

object

Additional HTTP headers to include in the request to the target API.

string

Request body for POST or PUT requests.

integer

required

Maximum micro-USDC to pay (safety cap). 1 USDC = 1,000,000 micro-USDC. Must be greater than 0 and at most 100,000,000 (100 USDC).

Response

integer

required

HTTP status code returned by the target API.

object

required

Response headers from the target API.

string

required

Response body from the target API.

integer

required

Actual micro-USDC charged. 0 if the target API did not require payment.

integer

required

Platform fee in micro-USDC.

string | null

required

On-chain settlement transaction hash. null if no payment was required.

boolean

required

Whether the payment was settled on-chain.

How It Works

The backend makes the initial request to the target URL.
If the API returns HTTP 402 Payment Required, the response body contains the x402 payment requirements.
The backend signs an EIP-3009 USDC authorization using the project’s x402 wallet key.
The request is retried with an X-PAYMENT header containing the signed payment.
The x402 facilitator verifies and settles the payment on-chain.
The API response is returned to the agent.
The USDC amount and platform fee are recorded in the project’s ledger.

If the target API does not return 402 (returns 200 directly), the response is passed through without any payment.

Examples

curl -X POST https://api.unwall.xyz/v1/x402/pay \
  -H "Authorization: Bearer aw_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/v1/premium-data",
    "method": "GET",
    "max_amount_usdc": 500000
  }'

import requests

resp = requests.post(
    "https://api.unwall.xyz/v1/x402/pay",
    headers={"Authorization": "Bearer aw_live_xxxxxxxxxxxx"},
    json={
        "url": "https://api.example.com/v1/premium-data",
        "method": "GET",
        "max_amount_usdc": 500000,
    },
)
result = resp.json()
print(f"Status: {result['status_code']}")
print(f"Paid: {result['payment_amount'] / 1_000_000} USDC")
print(f"Body: {result['body']}")

const resp = await fetch("https://api.unwall.xyz/v1/x402/pay", {
  method: "POST",
  headers: {
    Authorization: "Bearer aw_live_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://api.example.com/v1/premium-data",
    method: "GET",
    max_amount_usdc: 500000,
  }),
});
const result = await resp.json();
console.log(`Status: ${result.status_code}`);
console.log(`Paid: ${result.payment_amount / 1_000_000} USDC`);
console.log(`Body: ${result.body}`);

Response (200 OK)

{
  "status_code": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"data\": [{\"id\": 1, \"value\": \"premium result\"}]}",
  "payment_amount": 100000,
  "fee_amount": 1500,
  "tx_hash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
  "settled": true
}

Errors

Status	Cause
`400`	`max_amount_usdc` exceeded by the API’s payment requirement
`400`	Insufficient USDC balance
`403`	Token lacks `x402` permission
`502`	Target API or x402 facilitator returned an error

The max_amount_usdc is a safety cap. If the target API requests more USDC than your max, the payment is rejected and the request fails with a 400 error. Always set a reasonable max for the API you are calling.

API Reference

Agent API

x402 Pay

Request Body

Response

How It Works

Examples

Errors

​Request Body

​Response

​How It Works

​Examples

​Errors

Request Body

Response

How It Works

Examples

Errors