X402 - Permissions

Settle Permission

Finalizes and records delegated permission usage after service delivery.

post/x402/settle

Request

  • Base URL: https://api.sandbox.nevermined.app/api/v1
  • URL: https://api.sandbox.nevermined.app/api/v1/x402/settle
  • Auth: HTTP bearer

Request body

x402AccessTokenstring required

The x402 payment payload, base64-encoded — the token minted by POST /x402/permissions.

maxAmountstring

Maximum credits to redeem during settlement. Send it as a decimal STRING: the value is parsed with BigInt() and then required to be a bigint, so a JSON number is rejected with 400.

agentRequestIdstring

Agent request id for observability, as returned by POST /x402/verify. Bounded to 1–128 URL-safe ASCII characters because the value is interpolated into a Helicone filter and persisted to agent_tasks.

batchboolean

Whether this settles a batch — several LLM calls made under one agentRequestId.

marginPercentnumber

Margin percentage used for credit calculation. Mutually exclusive with maxAmount when agentRequestId is supplied.

Example request

{
  "paymentRequired": {
    "x402Version": 2,
    "error": "Payment required to access resource",
    "resource": {
      "url": "https://myagent.ai/api/v1/tasks",
      "description": "AI agent task execution",
      "mimeType": "application/json"
    },
    "accepts": [
      {
        "scheme": "nvm:erc4337",
        "network": "eip155:84532",
        "planId": "44742763076047497640080230236781474129970992727896593861997347135613135571071",
        "extra": {
          "version": "1",
          "agentId": "80918427023170428029540261117198154464497879145267720259488529685089104529015",
          "httpVerb": "POST"
        }
      }
    ],
    "extensions": {}
  },
  "x402AccessToken": "eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9teWFnZW50LmFpL2FwaS92MS90YXNrcyJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJudm06ZXJjNDMzNyIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwbGFuSWQiOiI0NDc0Mjc2MzA3NjA0NzQ5NzY0MDA4MDIzMDIzNjc4MTQ3NDEyOTk3MDk5MjcyNzg5NjU5Mzg2MTk5NzM0NzEzNTYxMzEzNTU3MTA3MSIsImV4dHJhIjp7InZlcnNpb24iOiIxIiwiYWdlbnRJZCI6IjgwOTE4NDI3MDIzMTcwNDI4MDI5NTQwMjYxMTE3MTk4MTU0NDY0NDk3ODc5MTQ1MjY3NzIwMjU5NDg4NTI5Njg1MDg5MTA0NTI5MDE1IiwiaHR0cFZlcmIiOiJQT1NUIn19LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4MTIzNCIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4ZjM5RmQ2ZTUxYWFkODhGNkY0Y2U2YUI4ODI3Mjc5Y2ZmRmI5MjI2NiIsInNlc3Npb25LZXlzUHJvdmlkZXIiOiJ6ZXJvZGV2Iiwic2Vzc2lvbktleXMiOltdfX0sImV4dGVuc2lvbnMiOnt9fQ==",
  "maxAmount": "2",
  "agentRequestId": "arId-123e4567-e89b-12d3-a456-426614174000",
  "batch": true,
  "marginPercent": 0.2
}

Response

Settlement complete

successboolean

Whether settlement was successful.

errorReasonstring

Reason for settlement failure (only present if success is false).

payerstring

Address of the payer's wallet.

transactionstring

Blockchain transaction hash. On crypto pay-as-you-go plans this is also the reference for the per-request charge.

networkstring

Network identifier. The discriminator is the rail, not the billing model: a CAIP-2 chain id (eip155:84532) for crypto rails under both billing models, or the settling payment provider (stripe, braintree, visa) for fiat card-delegation rails.

billingModel'credits' | 'pay-as-you-go'

Which billing model this settle was priced under. Present regardless of success — check success before treating it as evidence of a charge. Read it before the two credit fields.

creditsRedeemedstring

Number of credits redeemed. Always "0" for pay-as-you-go plans, which hold no credit balance — including on a settle that charged the buyer successfully.

remainingBalancestring

Subscriber's remaining credit balance. Always "0" for pay-as-you-go plans — the per-request charge is referenced by orderTx (fiat) or transaction (crypto), not here.

orderTxstring

Reference for the order or per-request charge, if one occurred. On fiat pay-as-you-go this is the per-request charge (a Stripe PaymentIntent id, a Braintree transaction id); crypto pay-as-you-go reports its on-chain order in transaction instead. On credits plans it is set only when the settle had to order credits first (auto top-up).

Example response

{
  "network": "eip155:84532",
  "creditsRedeemed": "2",
  "remainingBalance": "98",
  "orderTx": "pi_3TUrvfBYvSRKcV420xCBjHb1"
}

Changes

No recorded changes to this operation across all 1 revision of this API.