Settle an x402 payment
curl --request POST \
--url https://api.circle.com/v1/facilitator/x402/settle \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"x402Version": 2,
"paymentPayload": {
"x402Version": 2,
"accepted": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
},
"payload": {
"signature": "0x...",
"authorization": {
"from": "0x9aE2...",
"to": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"value": "1000000",
"validAfter": "0",
"validBefore": "1781308800",
"nonce": "0x4d3f..."
}
},
"resource": {
"url": "https://api.example.com/premium",
"description": "Premium report",
"mimeType": "application/json"
},
"extensions": {
"payment-identifier": {
"info": {
"required": true,
"id": "pay_5f0d3c1a9b7e4d2c"
}
}
}
},
"paymentRequirements": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
}
}
'import requests
url = "https://api.circle.com/v1/facilitator/x402/settle"
payload = {
"x402Version": 2,
"paymentPayload": {
"x402Version": 2,
"accepted": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
},
"payload": {
"signature": "0x...",
"authorization": {
"from": "0x9aE2...",
"to": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"value": "1000000",
"validAfter": "0",
"validBefore": "1781308800",
"nonce": "0x4d3f..."
}
},
"resource": {
"url": "https://api.example.com/premium",
"description": "Premium report",
"mimeType": "application/json"
},
"extensions": { "payment-identifier": { "info": {
"required": True,
"id": "pay_5f0d3c1a9b7e4d2c"
} } }
},
"paymentRequirements": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
x402Version: 2,
paymentPayload: {
x402Version: 2,
accepted: {
scheme: 'exact',
network: 'eip155:5042002',
amount: '1000000',
asset: '0x3600000000000000000000000000000000000000',
payTo: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
maxTimeoutSeconds: 12,
extra: {name: 'USDC', version: '2', assetTransferMethod: 'eip3009'}
},
payload: {
signature: '0x...',
authorization: {
from: '0x9aE2...',
to: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
value: '1000000',
validAfter: '0',
validBefore: '1781308800',
nonce: '0x4d3f...'
}
},
resource: {
url: 'https://api.example.com/premium',
description: 'Premium report',
mimeType: 'application/json'
},
extensions: {'payment-identifier': {info: {required: true, id: 'pay_5f0d3c1a9b7e4d2c'}}}
},
paymentRequirements: {
scheme: 'exact',
network: 'eip155:5042002',
amount: '1000000',
asset: '0x3600000000000000000000000000000000000000',
payTo: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
maxTimeoutSeconds: 12,
extra: {name: 'USDC', version: '2', assetTransferMethod: 'eip3009'}
}
})
};
fetch('https://api.circle.com/v1/facilitator/x402/settle', 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.circle.com/v1/facilitator/x402/settle",
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([
'x402Version' => 2,
'paymentPayload' => [
'x402Version' => 2,
'accepted' => [
'scheme' => 'exact',
'network' => 'eip155:5042002',
'amount' => '1000000',
'asset' => '0x3600000000000000000000000000000000000000',
'payTo' => '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
'maxTimeoutSeconds' => 12,
'extra' => [
'name' => 'USDC',
'version' => '2',
'assetTransferMethod' => 'eip3009'
]
],
'payload' => [
'signature' => '0x...',
'authorization' => [
'from' => '0x9aE2...',
'to' => '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
'value' => '1000000',
'validAfter' => '0',
'validBefore' => '1781308800',
'nonce' => '0x4d3f...'
]
],
'resource' => [
'url' => 'https://api.example.com/premium',
'description' => 'Premium report',
'mimeType' => 'application/json'
],
'extensions' => [
'payment-identifier' => [
'info' => [
'required' => true,
'id' => 'pay_5f0d3c1a9b7e4d2c'
]
]
]
],
'paymentRequirements' => [
'scheme' => 'exact',
'network' => 'eip155:5042002',
'amount' => '1000000',
'asset' => '0x3600000000000000000000000000000000000000',
'payTo' => '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
'maxTimeoutSeconds' => 12,
'extra' => [
'name' => 'USDC',
'version' => '2',
'assetTransferMethod' => 'eip3009'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.circle.com/v1/facilitator/x402/settle"
payload := strings.NewReader("{\n \"x402Version\": 2,\n \"paymentPayload\": {\n \"x402Version\": 2,\n \"accepted\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n },\n \"payload\": {\n \"signature\": \"0x...\",\n \"authorization\": {\n \"from\": \"0x9aE2...\",\n \"to\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"value\": \"1000000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"1781308800\",\n \"nonce\": \"0x4d3f...\"\n }\n },\n \"resource\": {\n \"url\": \"https://api.example.com/premium\",\n \"description\": \"Premium report\",\n \"mimeType\": \"application/json\"\n },\n \"extensions\": {\n \"payment-identifier\": {\n \"info\": {\n \"required\": true,\n \"id\": \"pay_5f0d3c1a9b7e4d2c\"\n }\n }\n }\n },\n \"paymentRequirements\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.circle.com/v1/facilitator/x402/settle")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"x402Version\": 2,\n \"paymentPayload\": {\n \"x402Version\": 2,\n \"accepted\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n },\n \"payload\": {\n \"signature\": \"0x...\",\n \"authorization\": {\n \"from\": \"0x9aE2...\",\n \"to\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"value\": \"1000000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"1781308800\",\n \"nonce\": \"0x4d3f...\"\n }\n },\n \"resource\": {\n \"url\": \"https://api.example.com/premium\",\n \"description\": \"Premium report\",\n \"mimeType\": \"application/json\"\n },\n \"extensions\": {\n \"payment-identifier\": {\n \"info\": {\n \"required\": true,\n \"id\": \"pay_5f0d3c1a9b7e4d2c\"\n }\n }\n }\n },\n \"paymentRequirements\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.circle.com/v1/facilitator/x402/settle")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"x402Version\": 2,\n \"paymentPayload\": {\n \"x402Version\": 2,\n \"accepted\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n },\n \"payload\": {\n \"signature\": \"0x...\",\n \"authorization\": {\n \"from\": \"0x9aE2...\",\n \"to\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"value\": \"1000000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"1781308800\",\n \"nonce\": \"0x4d3f...\"\n }\n },\n \"resource\": {\n \"url\": \"https://api.example.com/premium\",\n \"description\": \"Premium report\",\n \"mimeType\": \"application/json\"\n },\n \"extensions\": {\n \"payment-identifier\": {\n \"info\": {\n \"required\": true,\n \"id\": \"pay_5f0d3c1a9b7e4d2c\"\n }\n }\n }\n },\n \"paymentRequirements\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"payer": "0x9aE2...",
"transaction": "0x6f9e1d...",
"network": "eip155:5042002",
"amount": "1000000",
"errorReason": "invalid_exact_evm_payload_signature",
"extensions": {
"settlement-status": {
"status": "pending",
"paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
"statusUrl": "https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa"
}
}
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}Settle an x402 payment
Settles an x402 payment. Facilitator Service validates the buyer’s EIP-3009 authorization, screens both parties, records the payment, and submits the USDC transfer through a Circle relayer.
A settlement outcome always uses HTTP 200; there is no pending status
code. A terminal result means settlement resolved within the HTTP wait
window. If the outcome is unresolved at the wait deadline, the 200
response carries success: false with
errorReason: settlement_pending and a paymentId. Pending is not
failure: settlement continues, and
Get payment status
reconciles the outcome. Do not fulfill on pending.
A rejected request or an internal failure uses the 4xx and 5xx codes below instead, and carries no settlement outcome.
Include a payment-identifier extension in the request body for
idempotency scoped to your seller account. Retries with the same
identifier converge on the same payment. Without an identifier, a
retry must reuse the exact same signed buyer authorization or the
retry is treated as a new charge.
POST
/
v1
/
facilitator
/
x402
/
settle
Settle an x402 payment
curl --request POST \
--url https://api.circle.com/v1/facilitator/x402/settle \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"x402Version": 2,
"paymentPayload": {
"x402Version": 2,
"accepted": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
},
"payload": {
"signature": "0x...",
"authorization": {
"from": "0x9aE2...",
"to": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"value": "1000000",
"validAfter": "0",
"validBefore": "1781308800",
"nonce": "0x4d3f..."
}
},
"resource": {
"url": "https://api.example.com/premium",
"description": "Premium report",
"mimeType": "application/json"
},
"extensions": {
"payment-identifier": {
"info": {
"required": true,
"id": "pay_5f0d3c1a9b7e4d2c"
}
}
}
},
"paymentRequirements": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
}
}
'import requests
url = "https://api.circle.com/v1/facilitator/x402/settle"
payload = {
"x402Version": 2,
"paymentPayload": {
"x402Version": 2,
"accepted": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
},
"payload": {
"signature": "0x...",
"authorization": {
"from": "0x9aE2...",
"to": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"value": "1000000",
"validAfter": "0",
"validBefore": "1781308800",
"nonce": "0x4d3f..."
}
},
"resource": {
"url": "https://api.example.com/premium",
"description": "Premium report",
"mimeType": "application/json"
},
"extensions": { "payment-identifier": { "info": {
"required": True,
"id": "pay_5f0d3c1a9b7e4d2c"
} } }
},
"paymentRequirements": {
"scheme": "exact",
"network": "eip155:5042002",
"amount": "1000000",
"asset": "0x3600000000000000000000000000000000000000",
"payTo": "0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a",
"maxTimeoutSeconds": 12,
"extra": {
"name": "USDC",
"version": "2",
"assetTransferMethod": "eip3009"
}
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
x402Version: 2,
paymentPayload: {
x402Version: 2,
accepted: {
scheme: 'exact',
network: 'eip155:5042002',
amount: '1000000',
asset: '0x3600000000000000000000000000000000000000',
payTo: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
maxTimeoutSeconds: 12,
extra: {name: 'USDC', version: '2', assetTransferMethod: 'eip3009'}
},
payload: {
signature: '0x...',
authorization: {
from: '0x9aE2...',
to: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
value: '1000000',
validAfter: '0',
validBefore: '1781308800',
nonce: '0x4d3f...'
}
},
resource: {
url: 'https://api.example.com/premium',
description: 'Premium report',
mimeType: 'application/json'
},
extensions: {'payment-identifier': {info: {required: true, id: 'pay_5f0d3c1a9b7e4d2c'}}}
},
paymentRequirements: {
scheme: 'exact',
network: 'eip155:5042002',
amount: '1000000',
asset: '0x3600000000000000000000000000000000000000',
payTo: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
maxTimeoutSeconds: 12,
extra: {name: 'USDC', version: '2', assetTransferMethod: 'eip3009'}
}
})
};
fetch('https://api.circle.com/v1/facilitator/x402/settle', 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.circle.com/v1/facilitator/x402/settle",
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([
'x402Version' => 2,
'paymentPayload' => [
'x402Version' => 2,
'accepted' => [
'scheme' => 'exact',
'network' => 'eip155:5042002',
'amount' => '1000000',
'asset' => '0x3600000000000000000000000000000000000000',
'payTo' => '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
'maxTimeoutSeconds' => 12,
'extra' => [
'name' => 'USDC',
'version' => '2',
'assetTransferMethod' => 'eip3009'
]
],
'payload' => [
'signature' => '0x...',
'authorization' => [
'from' => '0x9aE2...',
'to' => '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
'value' => '1000000',
'validAfter' => '0',
'validBefore' => '1781308800',
'nonce' => '0x4d3f...'
]
],
'resource' => [
'url' => 'https://api.example.com/premium',
'description' => 'Premium report',
'mimeType' => 'application/json'
],
'extensions' => [
'payment-identifier' => [
'info' => [
'required' => true,
'id' => 'pay_5f0d3c1a9b7e4d2c'
]
]
]
],
'paymentRequirements' => [
'scheme' => 'exact',
'network' => 'eip155:5042002',
'amount' => '1000000',
'asset' => '0x3600000000000000000000000000000000000000',
'payTo' => '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a',
'maxTimeoutSeconds' => 12,
'extra' => [
'name' => 'USDC',
'version' => '2',
'assetTransferMethod' => 'eip3009'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.circle.com/v1/facilitator/x402/settle"
payload := strings.NewReader("{\n \"x402Version\": 2,\n \"paymentPayload\": {\n \"x402Version\": 2,\n \"accepted\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n },\n \"payload\": {\n \"signature\": \"0x...\",\n \"authorization\": {\n \"from\": \"0x9aE2...\",\n \"to\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"value\": \"1000000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"1781308800\",\n \"nonce\": \"0x4d3f...\"\n }\n },\n \"resource\": {\n \"url\": \"https://api.example.com/premium\",\n \"description\": \"Premium report\",\n \"mimeType\": \"application/json\"\n },\n \"extensions\": {\n \"payment-identifier\": {\n \"info\": {\n \"required\": true,\n \"id\": \"pay_5f0d3c1a9b7e4d2c\"\n }\n }\n }\n },\n \"paymentRequirements\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.circle.com/v1/facilitator/x402/settle")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"x402Version\": 2,\n \"paymentPayload\": {\n \"x402Version\": 2,\n \"accepted\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n },\n \"payload\": {\n \"signature\": \"0x...\",\n \"authorization\": {\n \"from\": \"0x9aE2...\",\n \"to\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"value\": \"1000000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"1781308800\",\n \"nonce\": \"0x4d3f...\"\n }\n },\n \"resource\": {\n \"url\": \"https://api.example.com/premium\",\n \"description\": \"Premium report\",\n \"mimeType\": \"application/json\"\n },\n \"extensions\": {\n \"payment-identifier\": {\n \"info\": {\n \"required\": true,\n \"id\": \"pay_5f0d3c1a9b7e4d2c\"\n }\n }\n }\n },\n \"paymentRequirements\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.circle.com/v1/facilitator/x402/settle")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"x402Version\": 2,\n \"paymentPayload\": {\n \"x402Version\": 2,\n \"accepted\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n },\n \"payload\": {\n \"signature\": \"0x...\",\n \"authorization\": {\n \"from\": \"0x9aE2...\",\n \"to\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"value\": \"1000000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"1781308800\",\n \"nonce\": \"0x4d3f...\"\n }\n },\n \"resource\": {\n \"url\": \"https://api.example.com/premium\",\n \"description\": \"Premium report\",\n \"mimeType\": \"application/json\"\n },\n \"extensions\": {\n \"payment-identifier\": {\n \"info\": {\n \"required\": true,\n \"id\": \"pay_5f0d3c1a9b7e4d2c\"\n }\n }\n }\n },\n \"paymentRequirements\": {\n \"scheme\": \"exact\",\n \"network\": \"eip155:5042002\",\n \"amount\": \"1000000\",\n \"asset\": \"0x3600000000000000000000000000000000000000\",\n \"payTo\": \"0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a\",\n \"maxTimeoutSeconds\": 12,\n \"extra\": {\n \"name\": \"USDC\",\n \"version\": \"2\",\n \"assetTransferMethod\": \"eip3009\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"payer": "0x9aE2...",
"transaction": "0x6f9e1d...",
"network": "eip155:5042002",
"amount": "1000000",
"errorReason": "invalid_exact_evm_payload_signature",
"extensions": {
"settlement-status": {
"status": "pending",
"paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
"statusUrl": "https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa"
}
}
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}{
"code": 403,
"message": "Registration required to continue settling on this address",
"errors": [
{
"reason": "registration_required"
}
]
}Authorizations
CircleApiKeyFacilitatorSellerProof
Bearer token authentication with a Circle API key. Use this for
production settlement. Settling with an API key also binds the payTo
to your Circle account, which ends the keyless trial allowance.
Body
application/json
x402 protocol version. Facilitator Service supports version 2.
Available options:
2 x402 v2 payment payload. Includes the payment terms the buyer accepted and the signed EIP-3009 authorization that authorizes the USDC transfer.
Show child attributes
Show child attributes
Payment terms the seller advertises for an x402 resource. Facilitator Service validates that the buyer's authorization matches these requirements.
Show child attributes
Show child attributes
Response
Terminal or unresolved settlement result
Whether the transfer settled onchain within the wait window. Check the
settlement-status extension to distinguish failed from pending.
Example:
true
Buyer address recovered from the signed authorization.
Example:
"0x9aE2..."
Transaction hash on terminal success. Empty string when settlement is still pending or failed before submission.
Example:
"0x6f9e1d..."
CAIP-2 network identifier for the settled payment.
Example:
"eip155:5042002"
Amount in atomic USDC units.
Example:
"1000000"
Reason code. Present whenever success is false, either because the
payment failed terminally or because the outcome was unresolved at
the wait deadline (settlement_pending).
Available options:
settlement_pending, invalid_x402_version, unsupported_scheme, invalid_network, invalid_payment_requirements, invalid_payload, invalid_exact_evm_payload_recipient_mismatch, invalid_exact_evm_payload_authorization_value_mismatch, invalid_exact_evm_payload_authorization_valid_after, invalid_exact_evm_payload_authorization_valid_before, invalid_exact_evm_payload_signature, invalid_transaction_state, insufficient_funds Example:
"invalid_exact_evm_payload_signature"
x402 extensions. Facilitator Service returns a settlement-status
extension only after a payment has been recorded — on
settlement_pending and on terminal failures that have a
paymentId. Pre-recording validation failures (invalid_x402_version,
unsupported_scheme, invalid_network,
invalid_payment_requirements, invalid_payload, and the other
request-validation errorReason values) return success: false with
an errorReason and no extension, because there is no paymentId to
reconcile. When present, the extension carries status, paymentId,
and statusUrl. Settlement returns no poll hints.
Example:
{
"settlement-status": {
"status": "pending",
"paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
"statusUrl": "https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa"
}
}
Was this page helpful?