Settle

Broadcasts the payment on-chain and returns the transaction signature. Re-runs screening, de-duplicates the transaction in case of a double settle, then co-signs as fee-payer and submits. /settle is effectively synchronous — it returns once the transaction lands or fails. The request body is identical to /verify.

Always /verify first. /settle will re-screen and re-check, but verifying up front means you don't broadcast a transaction that was never going to land — and you don't hold the buyer's connection open for a settle that fails fast.

Protocol-level failures return HTTP 200 with { success: false, errorReason }. Only a malformed request body returns 4xx.

Request body — same shape as /verify.

Response 200 OK — settled

{
  "success": true,
  "transaction": "5KtPn1…solana-tx-signature",
  "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
  "payer": "BuyerWalletAddress…"
}

The transaction is the on-chain signature — view it at https://explorer.solana.com/tx/<transaction>.

Response 200 OK — rejected (still HTTP 200)

{
  "success": false,
  "errorReason": "duplicate_settle_in_flight",
  "transaction": "",
  "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
}

Field	Type	Description
`success`	boolean	`true` only if the transaction was broadcast and confirmed.
`transaction`	string	On-chain transaction signature on success; empty string on failure.
`network`	string	CAIP-2 network the settle ran on, echoed back.
`payer`	string	(optional) The buyer's wallet address.
`errorReason`	string	Present when `success` is `false`. Machine-readable code (see Reason codes).
`errorMessage`	string	(optional) Human-readable elaboration on `errorReason`.
`amount`	string	(optional) Actual atomic units settled. For `exact` this matches the requested amount.

Error reason codes (non-exhaustive)

Code	Meaning
`sanctioned_address` / `screener_unavailable`	Same as verify — screening blocked the settle.
`invalid_payload`	Couldn't decode the buyer's transaction to extract the payer.
`unsupported_network`	No adapter registered for the requested network.
`duplicate_settle_in_flight`	Another replica already reserved this exact payment within the dedup window.
`duplicate_settlement`	The transfer was already settled on-chain.
`transaction_failed`	The transaction was broadcast but did not confirm.
`unexpected_settle_error`	Unhandled internal error.

x402Version

number

enum

required

x402 protocol version. Must be 2; this facilitator does not accept V1.

Allowed:

2

paymentPayload

object

required

x402 V2 payment payload envelope. The inner payload field is scheme-specific; see the examples for each supported (scheme, network) combination.

paymentPayloadobject

paymentRequirements

object

required

x402 V2 payment requirements envelope. The extra field is scheme-specific; see the examples for each supported (scheme, network) combination.

paymentRequirementsobject

``200 Settlement result (success or protocol-level failure).

object

success

boolean

required

errorReason

string

errorMessage

string

payer

string

transaction

string

required

network

string

required

^[^:]+:[^:]+$

CAIP-2-like network identifier in the form scheme:network.

amount

string

extensions

object

Has additional fields

extra

object

Has additional fields

``400 Malformed request body.

curl --request POST \

--url https://api.figment.io/x402/settle \

--header 'accept: application/json' \

--header 'content-type: application/json' \

--header 'x-api-key: your-api-key-here' \

--data '

{

"x402Version": 2,

"paymentPayload": {

"x402Version": 2

}

}

'

{
  "success": true,
  "errorReason": "string",
  "errorMessage": "string",
  "payer": "string",
  "transaction": "string",
  "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
  "amount": "string",
  "extensions": {},
  "extra": {}
}

Updated 22 days ago