Skip to content
Farcaster

Settle a verified payment (gateway → facilitator)

POST
/settle
curl --request POST \
  --url https://example.com/settle \
  --header 'Content-Type: application/json' \
  --data '{ "x402Version": 1, "paymentPayload": { "x402Version": 1, "scheme": "example", "network": "example", "payload": { "signature": "example", "authorization": { "from": "example", "to": "example", "value": "example", "validAfter": "example", "validBefore": "example", "nonce": "example" } } }, "paymentRequirements": { "scheme": "example", "network": "example", "maxAmountRequired": "example", "asset": "example", "payTo": "example", "resource": "example", "maxTimeoutSeconds": 1 } }'

Once a facilitator is configured, the gateway hands the same Payment it verified — plus the PaymentRequirements it issued — to the facilitator as a SettleRequest, and the facilitator answers with a SettleResponse. A failed settle reports { "success": false, "errorReason": "…" } — one coarse reason, never internal detail. facilitatorFee is an optional extension; the self-hosted default takes no cut and omits it.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

POST /settle request body — verified payment handed to the facilitator.

object
x402Version
required
integer
paymentPayload
required

The decoded X-PAYMENT header for the exact scheme.

object
x402Version
required
integer
scheme
required
string
network
required
string
payload
required

The exact-scheme payload — signature over the authorization.

object
signature
required
string
authorization
required

EIP-3009 transferWithAuthorization arguments the caller signed.

object
from
required

Payer address (hex)

string
to
required

Recipient address (hex)

string
value
required

Amount

string
validAfter
required

Unix seconds

string
validBefore
required

Unix seconds

string
nonce
required

Authorization nonce (hex)

string
paymentRequirements
required

One entry of a 402 challenge’s accepts array.

object
scheme
required
string
network
required
string
maxAmountRequired
required

Decimal string (256-bit)

string
asset
required

Token contract address (hex)

string
payTo
required
string
resource
required
string
maxTimeoutSeconds
required
integer
Examplegenerated
{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "example",
    "network": "example",
    "payload": {
      "signature": "example",
      "authorization": {
        "from": "example",
        "to": "example",
        "value": "example",
        "validAfter": "example",
        "validBefore": "example",
        "nonce": "example"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "example",
    "network": "example",
    "maxAmountRequired": "example",
    "asset": "example",
    "payTo": "example",
    "resource": "example",
    "maxTimeoutSeconds": 1
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

The settlement result.

Media typeapplication/json

POST /settle response body. facilitatorFee is an optional extension a fee-recovering facilitator may report; absent on a self-hosted one.

object
success
required
boolean
errorReason
string
transaction
string
network
string
payer
string
facilitatorFee
string
Examplegenerated
{
  "success": true,
  "errorReason": "example",
  "transaction": "example",
  "network": "example",
  "payer": "example",
  "facilitatorFee": "example"
}