From 8f32deea9040f62c1a69ba71685d3a43e152821a Mon Sep 17 00:00:00 2001 From: Joaquim Verges Date: Fri, 3 Oct 2025 10:28:45 +1300 Subject: [PATCH] [Docs] Simplify x402 documentation and rename "Facilitator API" to "Facilitator" --- .../settings/SponsorshipPolicies/index.tsx | 2 +- apps/portal/src/app/payments/sidebar.tsx | 2 +- .../src/app/payments/x402/client/page.mdx | 40 ++---------- .../app/payments/x402/facilitator/page.mdx | 9 ++- apps/portal/src/app/payments/x402/page.mdx | 4 ++ .../src/app/transactions/policies/page.mdx | 63 +++++++++++++++++++ apps/portal/src/app/transactions/sidebar.tsx | 4 ++ 7 files changed, 87 insertions(+), 37 deletions(-) create mode 100644 apps/portal/src/app/transactions/policies/page.mdx diff --git a/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/account-abstraction/settings/SponsorshipPolicies/index.tsx b/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/account-abstraction/settings/SponsorshipPolicies/index.tsx index 84c5c829047..80612ab72c2 100644 --- a/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/account-abstraction/settings/SponsorshipPolicies/index.tsx +++ b/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/account-abstraction/settings/SponsorshipPolicies/index.tsx @@ -552,7 +552,7 @@ export function AccountAbstractionSettingsPage( you build your own rules.{" "} diff --git a/apps/portal/src/app/payments/sidebar.tsx b/apps/portal/src/app/payments/sidebar.tsx index 8106521e9c1..8a699cdc60b 100644 --- a/apps/portal/src/app/payments/sidebar.tsx +++ b/apps/portal/src/app/payments/sidebar.tsx @@ -82,7 +82,7 @@ export const sidebar: SideBar = { }, { href: `${paymentsSlug}/x402/facilitator`, - name: "Facilitator API", + name: "Facilitator", }, ], name: "x402", diff --git a/apps/portal/src/app/payments/x402/client/page.mdx b/apps/portal/src/app/payments/x402/client/page.mdx index 99a46302a9f..4cc50219032 100644 --- a/apps/portal/src/app/payments/x402/client/page.mdx +++ b/apps/portal/src/app/payments/x402/client/page.mdx @@ -68,46 +68,18 @@ The client library wraps the native `fetch` API and handles: ## Prepare Payment - Create a signed payment header from the authenticated user to include in your API request: + Fetch any x402-compatible API and automatically handle payment flows when APIs return a `402 Payment Required` response using the authenticated wallet. - ### Making the Paid Request - - After preparing the payment, include it in your API request: + Only requires passing a 'url' and 'from' query parameters with the authenticated wallet address (server or user wallet) to complete the payment. ```bash - # First, make the initial request to get payment requirements - curl -X GET https://api.example.com/paid-endpoint - - # Response will be 402 Payment Required with payment details - # { - # "x402Version": 1, - # "accepts": [...payment requirements...], - # "error": "Payment required" - # } - - # Select one of the payment methods, and sign the payment authorization using the API - curl -X POST https://api.thirdweb.com/v1/payments/x402/prepare \ + curl -X POST https://api.thirdweb.com/v1/payments/x402/fetch?url=https://api.example.com/premium&from=0x1234... \ -H "Content-Type: application/json" \ - -H "Authorization: Bearer " \ - -d '{ - "from": "0x1234...", - "paymentRequirements": { ... } - }' - - # Response will contain the signed payment header - # { - # "paymentPayload": { ... }, - # "paymentHeader": "..." // base64 encoded payment header - # } - - # Finally, make the request with the payment header - curl -X GET https://api.example.com/paid-endpoint \ - -H "X-PAYMENT: " + -H "Authorization: Bearer " \ + -d '{ ... }' # request body passed through to the url called. ``` - ## API Reference - - + diff --git a/apps/portal/src/app/payments/x402/facilitator/page.mdx b/apps/portal/src/app/payments/x402/facilitator/page.mdx index 189089f6232..48f2f63f663 100644 --- a/apps/portal/src/app/payments/x402/facilitator/page.mdx +++ b/apps/portal/src/app/payments/x402/facilitator/page.mdx @@ -1,7 +1,7 @@ import { Tabs, TabsList, TabsTrigger, TabsContent, OpenApiEndpoint, Callout } from "@doc"; import { TypeScriptIcon, EngineIcon } from "@/icons"; -# Facilitator API +# Facilitator The facilitator is a service that handles verifying and submitting x402 payments. It uses your own [server wallet](/wallets/server) and leverages EIP-7702 to submit transactions gaslessly. @@ -16,6 +16,13 @@ The thirdweb facilitator is compatible with any x402 backend and middleware libr You can view all transactions processed by your facilitator in your project dashboard. +## Chain and token support + +Our facilitator supports payments on any EVM chain, as long as the payment token supports either: + +- ERC-2612 permit (most ERC20 tokens) +- ERC-3009 sign with authorization (USDC on all chains) + diff --git a/apps/portal/src/app/payments/x402/page.mdx b/apps/portal/src/app/payments/x402/page.mdx index 3429eff7ec4..22a2593b18d 100644 --- a/apps/portal/src/app/payments/x402/page.mdx +++ b/apps/portal/src/app/payments/x402/page.mdx @@ -33,6 +33,8 @@ const fetchWithPay = wrapFetchWithPayment(fetch, client, wallet); const response = await fetchWithPay('https://api.example.com/paid-endpoint'); ``` +You can also use the thirdweb API to fetch any x402 compatible endpoint and pay for it with the authenticated wallet. See the [client side docs](/payments/x402/client) for more details. + ## Server Side To make your API calls payable, use the `settlePayment` function in a middleware or endpoint: @@ -77,6 +79,8 @@ export async function GET(request: Request) { } ``` +You can also create middlewares to handle payment for multiple endpoints, see the [server side docs](/payments/x402/server) for more details. The [facilitator](/payments/x402/facilitator) handles settling the payment onchain using your own server wallet. + ## Going Further
diff --git a/apps/portal/src/app/transactions/policies/page.mdx b/apps/portal/src/app/transactions/policies/page.mdx new file mode 100644 index 00000000000..bc093923ae0 --- /dev/null +++ b/apps/portal/src/app/transactions/policies/page.mdx @@ -0,0 +1,63 @@ +# Gas Sponsorship Policies + +Sponsorship policies are a way to control the execution of sponsored transactions on your account. + +You can use them to: + +- Set global spend limits. +- Restrict sponsorship to a particular chain. +- Restrict sponsorship to a particular contract. +- Allow/Disallow specific wallets +- Setup your own server verifier. + +These policies can be set from your project dashboard, under project > account abstraction > settings. + +## Server Verifier + +The most flexible and powerful way to control the execution of sponsored transactions is to setup your own server verifier. + +In the project dashboard, under project > account abstraction > settings, setup your backend URL and any additional headers you need to pass to the verifier. + +On every user transaction, your backend will be called with the transaction data and the user's wallet address, your endpoint should return a boolean indicating whether the transaction should be sponsored. + +### Backend endpoint specification: + +Your backend will be called with the following request: + +```http +POST https://your-backend-url/verify-transaction +Content-Type: application/json +Referer: "https://api.thirdweb.com", +# additional custom headers + +# request body +{ + "clientId": string; + "chainId": number; + "userOp": { + sender: string; + targets: string[]; + gasLimit: string; + gasPrice: string; + data?: { + targets: string[]; + callDatas: string[]; + values: string[]; + }; + } +} +``` + +Your backend should process the request, apply your own policy logic based on the request data and return the following JSON response: + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "isAllowed": boolean; + "reason"?: string; +} +``` + +The `isAllowed` field indicates whether the transaction should be sponsored or not. `reason` is an optional field that can be used to provide a reason for the decision. \ No newline at end of file diff --git a/apps/portal/src/app/transactions/sidebar.tsx b/apps/portal/src/app/transactions/sidebar.tsx index d14878f9785..4882d3d5aa3 100644 --- a/apps/portal/src/app/transactions/sidebar.tsx +++ b/apps/portal/src/app/transactions/sidebar.tsx @@ -42,6 +42,10 @@ export const sidebar: SideBar = { href: `${transactionsSlug}/session-keys`, name: "Session Keys", }, + { + href: `${transactionsSlug}/policies`, + name: "Sponsorship Policies", + }, ], }, { separator: true },