From fb2c0fcf82217976e2c3c6c4317f9f9de94197e4 Mon Sep 17 00:00:00 2001 From: 0xFirekeeper <0xFirekeeper@gmail.com> Date: Sat, 6 Dec 2025 05:38:39 +0700 Subject: [PATCH 1/3] Add Solana facilitator guide to docs Introduces a new MDX guide for Solana facilitator integration under x402, detailing setup and API usage. Updates the sidebar to include a link to the new Solana guide for easier navigation. --- .../src/app/x402/facilitator/solana/page.mdx | 166 ++++++++++++++++++ apps/portal/src/app/x402/sidebar.tsx | 4 + 2 files changed, 170 insertions(+) create mode 100644 apps/portal/src/app/x402/facilitator/solana/page.mdx diff --git a/apps/portal/src/app/x402/facilitator/solana/page.mdx b/apps/portal/src/app/x402/facilitator/solana/page.mdx new file mode 100644 index 00000000000..3000e8ebcbd --- /dev/null +++ b/apps/portal/src/app/x402/facilitator/solana/page.mdx @@ -0,0 +1,166 @@ +import { Callout, createMetadata } from "@doc"; + +export const metadata = createMetadata({ + image: { + title: "Solana Facilitator", + icon: "solana", + }, + title: "Solana Facilitator", + description: "Verify and settle Solana transactions through your own facilitator wallets.", +}); + +# Solana Facilitator + +Solana is now a supported network for x402 payments. You can gate, verify, and settle Solana transactions through your own facilitator wallets — fully end-to-end. + +This enables you to spin up your own server wallet, prepare payment payloads, and handle verification + settlement directly on Solana (devnet or mainnet). No middle layers. No bloat. + +## Features + +- **Solana facilitator flow** — create or register a Solana server wallet, quote pricing with `/v1/payments/x402/accepts`, and settle signed transactions with `/v1/payments/x402/settle`. +- **Unified verify path** — `/v1/payments/x402/verify` now validates Solana payloads the same way it does for EVM, so you can reuse your middleware checks across chains. +- **End-to-end examples** — refreshed snippets for Node environments that show the exact headers, payloads, and success envelopes you should expect in production. + +## Fast Start Guide + +### 1. Create a facilitator wallet + +First, create a server-side wallet that will act as the facilitator. + +```ts +const response = await fetch("https://api.thirdweb.com/v1/solana/wallets", { + method: "POST", + headers: { + "x-secret-key": "YOUR_SECRET_KEY", + "Content-Type": "application/json", + }, + body: JSON.stringify({ + label: "my-solana-facilitator", + }), +}); + +const wallet = await response.json(); +console.log(wallet.result.address); +``` + +The returned address is the server-side payer for settles, so double-check that it appears in your project’s server wallet list. + + + **Fund the wallet:** Top up SOL for fees on the target cluster (devnet or mainnet-beta). + + +### 2. Quote access + +Use `/v1/payments/x402/accepts` to generate the payment requirements. + +```ts +const acceptsResponse = await fetch( + "https://api.thirdweb.com/v1/payments/x402/accepts", + { + method: "POST", + headers: { + "x-secret-key": "YOUR_SECRET_KEY", + "Content-Type": "application/json", + }, + body: JSON.stringify({ + resourceUrl: "https://example.com/solana-protected", + method: "POST", + network: "solana:8E9rvCKLFQia2Y35HXjjpWzj8weVo44K", + price: { + amount: "0", + asset: { + address: "So11111111111111111111111111111111111111112", + decimals: 9, + tokenProgram: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", + }, + }, + serverWalletAddress: "YOUR_SOLANA_FACILITATOR_ADDRESS", + }), + } +); + +const { accepts } = await acceptsResponse.json(); +const paymentRequirements = accepts[0]; +``` + +Keep `paymentRequirements` around—clients will sign against it, and the facilitator will reuse it when settling. + +### 3. Verify before you settle + +Once you have the signed payment payload from the client, you can verify it. + +```ts +const verifyResponse = await fetch( + "https://api.thirdweb.com/v1/payments/x402/verify", + { + method: "POST", + headers: { + "x-secret-key": "YOUR_SECRET_KEY", + "Content-Type": "application/json", + }, + body: JSON.stringify({ + paymentPayload: SIGNED_PAYMENT_PAYLOAD, + paymentRequirements, + }), + } +); + +const verifyData = await verifyResponse.json(); +console.log(verifyData.isValid); +``` + +A truthy `isValid` means the signatures, blockhash, and amounts all check out. + +### 4. Settle on-chain + +Settle the transaction using your facilitator wallet. + +```ts +const settleResponse = await fetch( + "https://api.thirdweb.com/v1/payments/x402/settle", + { + method: "POST", + headers: { + "x-secret-key": "YOUR_SECRET_KEY", + "Content-Type": "application/json", + }, + body: JSON.stringify({ + paymentPayload: SIGNED_PAYMENT_PAYLOAD, + paymentRequirements, + waitUntil: "submitted", + }), + } +); + +const settleData = await settleResponse.json(); +console.log(settleData.transaction); +``` + + + Use `waitUntil: "confirmed"` if you need finality before responding to the client. + + +Watch your server wallet dashboard or any Solana explorer for the transaction signature the settle endpoint returns. + +### Fetch protected resources + +Let payers fetch protected resources. If the client hits the protected endpoint first, have it replay the request through `/v1/payments/x402/fetch`. The API will answer with the payload you need for verification and settlement. + +```ts +const fetchResponse = await fetch( + "https://api.thirdweb.com/v1/payments/x402/fetch?" + + new URLSearchParams({ + url: "https://example.com/solana-protected", + from: "PAYER_SOLANA_ADDRESS", + chainId: "solana:8E9rvCKLFQia2Y35HXjjpWzj8weVo44K", + }), + { + method: "POST", + headers: { + "x-secret-key": "YOUR_SECRET_KEY", + }, + } +); + +const fetchData = await fetchResponse.json(); +``` diff --git a/apps/portal/src/app/x402/sidebar.tsx b/apps/portal/src/app/x402/sidebar.tsx index c17ed4ed195..8c4aa053bc3 100644 --- a/apps/portal/src/app/x402/sidebar.tsx +++ b/apps/portal/src/app/x402/sidebar.tsx @@ -37,6 +37,10 @@ export const sidebar: SideBar = { href: `${x402Slug}/facilitator`, name: "Facilitator", }, + { + href: `${x402Slug}/facilitator/solana`, + name: "Solana", + }, ], name: "Guides", }, From 515be123dfe198a9a4f7f8b6659a9705edaaca17 Mon Sep 17 00:00:00 2001 From: 0xFirekeeper <0xFirekeeper@gmail.com> Date: Sat, 6 Dec 2025 05:43:48 +0700 Subject: [PATCH 2/3] update sol caip2 supported --- .../src/app/x402/facilitator/solana/page.mdx | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/apps/portal/src/app/x402/facilitator/solana/page.mdx b/apps/portal/src/app/x402/facilitator/solana/page.mdx index 3000e8ebcbd..66754a8cea4 100644 --- a/apps/portal/src/app/x402/facilitator/solana/page.mdx +++ b/apps/portal/src/app/x402/facilitator/solana/page.mdx @@ -13,7 +13,14 @@ export const metadata = createMetadata({ Solana is now a supported network for x402 payments. You can gate, verify, and settle Solana transactions through your own facilitator wallets — fully end-to-end. -This enables you to spin up your own server wallet, prepare payment payloads, and handle verification + settlement directly on Solana (devnet or mainnet). No middle layers. No bloat. + + We support Solana Mainnet and Testnet. Use the following CAIP-2 chain IDs: + + - **Mainnet**: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` + - **Testnet**: `solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z` + + +This enables you to spin up your own server wallet, prepare payment payloads, and handle verification + settlement directly on Solana (testnet or mainnet). No middle layers. No bloat. ## Features @@ -46,7 +53,7 @@ console.log(wallet.result.address); The returned address is the server-side payer for settles, so double-check that it appears in your project’s server wallet list. - **Fund the wallet:** Top up SOL for fees on the target cluster (devnet or mainnet-beta). + **Fund the wallet:** Top up SOL for fees on the target cluster (testnet or mainnet-beta). ### 2. Quote access @@ -65,7 +72,7 @@ const acceptsResponse = await fetch( body: JSON.stringify({ resourceUrl: "https://example.com/solana-protected", method: "POST", - network: "solana:8E9rvCKLFQia2Y35HXjjpWzj8weVo44K", + network: "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z", price: { amount: "0", asset: { @@ -152,7 +159,7 @@ const fetchResponse = await fetch( new URLSearchParams({ url: "https://example.com/solana-protected", from: "PAYER_SOLANA_ADDRESS", - chainId: "solana:8E9rvCKLFQia2Y35HXjjpWzj8weVo44K", + chainId: "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z", }), { method: "POST", From edd71359d5ea1e77df823621afe16efa1e1c85df Mon Sep 17 00:00:00 2001 From: 0xFirekeeper <0xFirekeeper@gmail.com> Date: Sat, 6 Dec 2025 05:53:04 +0700 Subject: [PATCH 3/3] just slugs --- .../src/app/x402/facilitator/solana/page.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/apps/portal/src/app/x402/facilitator/solana/page.mdx b/apps/portal/src/app/x402/facilitator/solana/page.mdx index 66754a8cea4..53e40b5c088 100644 --- a/apps/portal/src/app/x402/facilitator/solana/page.mdx +++ b/apps/portal/src/app/x402/facilitator/solana/page.mdx @@ -14,13 +14,13 @@ export const metadata = createMetadata({ Solana is now a supported network for x402 payments. You can gate, verify, and settle Solana transactions through your own facilitator wallets — fully end-to-end. - We support Solana Mainnet and Testnet. Use the following CAIP-2 chain IDs: + We support Solana Mainnet and Devnet. Use the following network identifiers: - - **Mainnet**: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` - - **Testnet**: `solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z` + - **Mainnet**: `solana:mainnet` + - **Devnet**: `solana:devnet` -This enables you to spin up your own server wallet, prepare payment payloads, and handle verification + settlement directly on Solana (testnet or mainnet). No middle layers. No bloat. +This enables you to spin up your own server wallet, prepare payment payloads, and handle verification + settlement directly on Solana (devnet or mainnet). No middle layers. No bloat. ## Features @@ -53,7 +53,7 @@ console.log(wallet.result.address); The returned address is the server-side payer for settles, so double-check that it appears in your project’s server wallet list. - **Fund the wallet:** Top up SOL for fees on the target cluster (testnet or mainnet-beta). + **Fund the wallet:** Top up SOL for fees on the target cluster (devnet or mainnet-beta). ### 2. Quote access @@ -72,7 +72,7 @@ const acceptsResponse = await fetch( body: JSON.stringify({ resourceUrl: "https://example.com/solana-protected", method: "POST", - network: "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z", + network: "solana:devnet", price: { amount: "0", asset: { @@ -159,7 +159,7 @@ const fetchResponse = await fetch( new URLSearchParams({ url: "https://example.com/solana-protected", from: "PAYER_SOLANA_ADDRESS", - chainId: "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z", + chainId: "solana:devnet", }), { method: "POST",