{"id":33311632,"url":"https://github.com/snc2work/x402-facilitator-hono","last_synced_at":"2026-05-06T04:31:44.249Z","repository":{"id":323484244,"uuid":"1093419774","full_name":"snc2work/x402-facilitator-hono","owner":"snc2work","description":"A lightweight x402 payment facilitator built with Hono. An educational re-implementation of the official Coinbase example.","archived":false,"fork":false,"pushed_at":"2025-11-29T04:33:14.000Z","size":124,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-01T05:29:08.430Z","etag":null,"topics":["base-chain","facilitator","hono","solana","typescript","web3","x402"],"latest_commit_sha":null,"homepage":"https://github.com/coinbase/x402/tree/main/examples/typescript/facilitator","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snc2work.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-10T10:51:47.000Z","updated_at":"2025-11-29T04:33:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/snc2work/x402-facilitator-hono","commit_stats":null,"previous_names":["snc2work/x402-facilitator-hono"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/snc2work/x402-facilitator-hono","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snc2work%2Fx402-facilitator-hono","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snc2work%2Fx402-facilitator-hono/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snc2work%2Fx402-facilitator-hono/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snc2work%2Fx402-facilitator-hono/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snc2work","download_url":"https://codeload.github.com/snc2work/x402-facilitator-hono/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snc2work%2Fx402-facilitator-hono/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32678584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["base-chain","facilitator","hono","solana","typescript","web3","x402"],"created_at":"2025-11-19T05:01:51.032Z","updated_at":"2026-05-06T04:31:44.236Z","avatar_url":"https://github.com/snc2work.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# x402 Facilitator on Hono\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nA lightweight and efficient payment facilitator for the x402 standard, built with Hono. This server supports payment verification and settlement on multiple blockchains, such as Solana and Base.\n\n![x402 Facilitator Top Page](./assets/toppage.png)\n\n## ⚠️ Disclaimer and Important Notes\n\nThis project is a re-implementation of the official x402 facilitator example from Coinbase, which was originally written in Express. You can find the original example here:\n\n- **[coinbase/x402/examples/typescript/facilitator](https://github.com/coinbase/x402/tree/main/examples/typescript/facilitator)**\n\nThis implementation is intended for **educational and demonstrational purposes only**. It serves as a learning resource for those who want to build their own x402 facilitator using Hono.\n\n**Please DO NOT use this code in a production environment as-is.** Before considering deployment, you must thoroughly review and enhance the security, including the secure management of private keys, error handling, and overall robustness of the code to suit your specific needs.\n\nThis application is designed for deployment to Vercel.\nPlease be aware that you are responsible for all configurations and verifications necessary for a production environment. Use at your own risk.\n\n## ✨ Key Features\n\n- **Blazing Fast**: Built on top of [Hono](https://hono.dev/), one of the fastest web frameworks for JavaScript.\n- **Multi-Chain Support**: Supports payment handling on both the Solana (Mainnet, Devnet) and Base (Mainnet, Sepolia) blockchains.\n- **x402 Compliant**: Implements `verify` and `settle` endpoints for the x402 payment standard.\n- **Static Frontend**: A simple and informative landing page built with Hono's JSX and styled with Tailwind CSS.\n\n## 🛠️ Tech Stack\n\n- **Framework**: [Hono](https://hono.dev/)\n- **Runtime**: [Node.js](https://nodejs.org/)\n- **Language**: [TypeScript](https://www.typescriptlang.org/)\n- **UI Styling**: [Tailwind CSS](https://tailwindcss.com/)\n- **Testing**: [Vitest](https://vitest.dev/)\n- **Package Manager**: [Yarn](https://yarnpkg.com/) (with Corepack)\n\n## 🚀 Getting Started\n\nFollow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) (v20 LTS or later recommended)\n- [Yarn](https://yarnpkg.com/) (enabled via Corepack)\n\n### Installation \u0026 Setup\n\n1.  **Clone the repository:**\n\n    ```sh\n    git clone https://github.com/snc2work/x402-facilitator-hono.git\n    cd x402-facilitator-hono\n    ```\n\n2.  **Enable Corepack and set Yarn version:**\n    Corepack is the modern way to manage package managers.\n\n    ```sh\n    corepack enable\n    corepack use yarn@1\n    ```\n\n3.  **Install dependencies:**\n\n    ```sh\n    yarn install\n    ```\n\n4.  **Set up environment variables:**\n    Create a `.env` file in the root of the project by copying the example file. It's recommended to create a `.env.example` file in your repository for others.\n    ```sh\n    cp .env.example .env\n    ```\n    Now, open `.env` and fill in the required values.\n\n### Running the Development Server\n\nTo start the development server with hot-reloading:\n\n```sh\nyarn dev\n```\n\nThe server will be running at `http://localhost:3004` (or the port specified in your `.env`).\n\n## 💡 Tips for Buyers (Client-Side)\n\nThis section provides a tip for developers building a **Buyer application** on **Solana Mainnet** using `x402-fetch`.\n\nWhen using libraries like `x402-fetch`, you may encounter issues on Solana Mainnet. The default public RPC URL used internally by these libraries is often heavily rate-limited, which can cause payment verification or settlement to fail.\n\nFor more reliable operation, you can also use a dedicated RPC provider such as Helius or QuickNode. You can pass your custom RPC URL via the `svmConfig` option.\n\nThe following example applies to **`x402-fetch` version `^0.7.0`**. The specifications may differ in future versions.\n\nHere is a practical example of how to configure `wrapFetchWithPayment` with a custom Helius RPC URL:\n\n```typescript\nimport { wrapFetchWithPayment, createSigner } from \"x402-fetch\";\n\nconst solanaPrivateKey = process.env.SOLANA_PRIVATE_KEY;\nconst signer = await createSigner(\"solana\", solanaPrivateKey);\n\nconst heliusApiKey = process.env.HELIUS_API_KEY;\nconst heliusRpcUrl = `https://mainnet.helius-rpc.com/?api-key=${heliusApiKey}`;\n\n// Wrap the fetch function, providing the custom RPC URL via svmConfig.\nconst fetchWithPayment = wrapFetchWithPayment(\n  fetch,\n  signer,\n  undefined,\n  undefined,\n  {\n    svmConfig: {\n      rpcUrl: heliusRpcUrl,\n    },\n  }\n);\n```\n\n## ⚙️ Environment Variables\n\nThe following environment variables are required for the application to run. Create a `.env` file in the project root.\n\n```env\n# Node environment (development, production, test)\nNODE_ENV=development\n\n# Server port (e.g., 3002)\nPORT=3002\n\n# Allowed origins for CORS (e.g., http://localhost:3000,https://example.com)\nALLOWED_ORIGINS=\n\n# Comma-separated list of supported networks\nSUPPORTED_NETWORKS=base,base-sepolia,solana,solana-devnet\n\n# EVM private key for settling payments (e.g., 0x...)\nEVM_PRIVATE_KEY=your-key\n\n# SVM private key for settling payments (Base58 encoded)\nSVM_PRIVATE_KEY=your-key\n\n# -----------------------------------------------------------------\n# Optional but Recommended: RPC URLs for Solana networks\n# Public RPCs may be rate-limited. For reliable performance, especially on mainnet,\n# it is highly recommended to use a dedicated RPC provider like Helius or QuickNode.\n# -----------------------------------------------------------------\nSOLANA_RPC_URL=\nSOLANA_DEVNET_RPC_URL=\n```\n\n## 📜 Available Scripts\n\n- `yarn dev`: Starts the development server with live reloading.\n- `yarn build`: Compiles the TypeScript code and builds assets for production.\n- `yarn start`: Starts the production server from the `dist` directory.\n- `yarn test`: Runs the test suite using Vitest.\n\n## 📡 API Endpoints\n\nThe server provides the following API endpoints. The root path (`GET /`) serves the HTML landing page.\n\n| Method | Path         |\n| ------ | ------------ |\n| `GET`  | `/health`    |\n| `GET`  | `/supported` |\n| `GET`  | `/verify`    |\n| `POST` | `/verify`    |\n| `GET`  | `/settle`    |\n| `POST` | `/settle`    |\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) and [NOTICE](./NOTICE) files for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnc2work%2Fx402-facilitator-hono","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnc2work%2Fx402-facilitator-hono","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnc2work%2Fx402-facilitator-hono/lists"}