{"id":50682271,"url":"https://github.com/albttx/traefik-plugin-x402","last_synced_at":"2026-07-01T07:30:43.809Z","repository":{"id":367359857,"uuid":"1231813852","full_name":"albttx/traefik-plugin-x402","owner":"albttx","description":"traefik plugin for processing x402 payments","archived":false,"fork":false,"pushed_at":"2026-05-08T11:50:53.000Z","size":465,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-25T18:02:47.269Z","etag":null,"topics":["traefik","traefik-plugin","x402"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albttx.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":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T10:06:50.000Z","updated_at":"2026-05-24T00:33:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"689a778b-f8fe-4972-bdb9-fe57ee04d6ed","html_url":"https://github.com/albttx/traefik-plugin-x402","commit_stats":null,"previous_names":["albttx/traefik-plugin-x402"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/albttx/traefik-plugin-x402","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albttx%2Ftraefik-plugin-x402","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albttx%2Ftraefik-plugin-x402/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albttx%2Ftraefik-plugin-x402/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albttx%2Ftraefik-plugin-x402/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albttx","download_url":"https://codeload.github.com/albttx/traefik-plugin-x402/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albttx%2Ftraefik-plugin-x402/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34997946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["traefik","traefik-plugin","x402"],"created_at":"2026-06-08T20:00:23.299Z","updated_at":"2026-07-01T07:30:43.803Z","avatar_url":"https://github.com/albttx.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/banner.png\" alt=\"traefik-plugin-x402\" /\u003e\n\u003c/p\u003e\n\n# traefik-plugin-x402\n\nTraefik v3 middleware that gates HTTP routes behind on-chain stablecoin micropayments using the [x402 protocol](https://x402.org).\n\n[![tests](https://github.com/albttx/traefik-plugin-x402/actions/workflows/test.yml/badge.svg)](https://github.com/albttx/traefik-plugin-x402/actions/workflows/test.yml)\n![Go version](https://img.shields.io/badge/go-1.24-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\u003c!-- Traefik Plugin Catalog badge: add once the plugin is listed at https://plugins.traefik.io --\u003e\n\n---\n\n## Why\n\nPut any HTTP service behind a paywall without touching its source code. A client that cannot pay gets a standard `402 Payment Required` with a machine-readable `PaymentRequirements` body. A client that can pay signs the payment off-chain, retries the request, and the middleware handles verify-and-settle against a remote facilitator — no custom backend logic required.\n\nThe default facilitator is Coinbase's public `https://x402.org/facilitator`, free to use on Base Sepolia. USDC on Base / Base Sepolia is the primary supported asset.\n\nThe plugin has **zero non-stdlib runtime dependencies** and is interpreted by [Yaegi](https://github.com/traefik/yaegi) at Traefik startup. It never touches private keys or constructs on-chain transactions — all cryptographic verification and settlement is delegated to the facilitator over plain HTTPS JSON.\n\n---\n\n## How it works\n\n```\nClient                   Traefik (x402 middleware)        Facilitator          Upstream\n  |                              |                              |                   |\n  |--- GET /api ---------------\u003e |                              |                   |\n  |\u003c-- 402 PaymentRequirements --|                              |                   |\n  |                              |                              |                   |\n  |--- GET /api                  |                              |                   |\n  |    X-PAYMENT: \u003cbase64\u003e ----\u003e |                              |                   |\n  |                              |--- POST /verify -----------\u003e |                   |\n  |                              |\u003c-- { isValid: true } ------- |                   |\n  |                              |                              |                   |\n  |                              |--- forward request -----------------------------\u003e|\n  |                              |\u003c-- 200 body (buffered) --------------------------|\n  |                              |                              |                   |\n  |                              |--- POST /settle ------------\u003e|                   |\n  |                              |\u003c-- { success: true } --------|                   |\n  |                              |                              |                   |\n  |\u003c-- 200 body                  |                              |                   |\n  |    X-PAYMENT-RESPONSE: \u003cb64\u003e |                              |                   |\n```\n\n1. **No `X-PAYMENT` header** — middleware returns `402` with a `PaymentRequirements` JSON body. No upstream call is made.\n2. **`X-PAYMENT` present** — middleware base64-decodes the header, JSON-parses the `PaymentPayload`, and POSTs to `{facilitatorURL}/verify`.\n3. **Verify fails** — middleware returns `402` with the failure reason. No upstream call is made.\n4. **Verify succeeds** — middleware forwards the request to the upstream and **buffers the full response body**.\n5. **Upstream returns 2xx** — middleware POSTs to `{facilitatorURL}/settle`. On success, adds `X-PAYMENT-RESPONSE` (base64 JSON containing the on-chain tx hash) to the response. If settle fails, the 2xx is replaced with a `402`.\n6. **Upstream returns non-2xx** — settle is skipped; the buffered error response is forwarded as-is.\n\n\u003e Streaming responses are not supported — the upstream response is always fully buffered before settle is attempted.\n\n---\n\n## Install\n\n### Option A — Traefik Plugin Catalog (recommended)\n\n\u003e Available once the plugin is listed at https://plugins.traefik.io.\n\nIn Traefik's **static configuration**:\n\n```yaml\n# traefik.yml\nexperimental:\n  plugins:\n    x402:\n      moduleName: github.com/albttx/traefik-plugin-x402\n      version: v0.1.0   # replace with the latest tagged release\n```\n\n### Option B — Local plugin (self-hosted / air-gapped)\n\nMount the plugin source under Traefik's plugin directory at the path matching its module name:\n\n```\n/plugins-local/\n  src/\n    github.com/\n      albttx/\n        traefik-plugin-x402/\n          plugin.go\n          go.mod\n          .traefik.yml\n          internal/\n            x402/\n```\n\nThen in static config:\n\n```yaml\n# traefik.yml\nexperimental:\n  localPlugins:\n    x402:\n      moduleName: github.com/albttx/traefik-plugin-x402\n```\n\n---\n\n## Configure\n\n### Options\n\n| Name | Required | Default | Description |\n|---|---|---|---|\n| `payTo` | yes | — | Recipient wallet address (EVM checksum address) |\n| `network` | yes | — | Network identifier, e.g. `base`, `base-sepolia` |\n| `asset` | yes | — | ERC-20 contract address of the payment token |\n| `amount` | yes | — | Amount in atomic units as a decimal string. USDC has 6 decimals, so `\"1000\"` = $0.001 |\n| `assetName` | yes¹ | `\"\"` | EIP-712 domain `name` for the asset. For Circle USDC: `USDC`. |\n| `assetVersion` | yes¹ | `\"\"` | EIP-712 domain `version` for the asset. For Circle USDC: `2`. |\n| `description` | no | `\"\"` | Human-readable description included in the `PaymentRequirements` |\n| `mimeType` | no | `application/json` | MIME type of the protected resource |\n| `resource` | no | full request URL | Override the resource URL advertised in `PaymentRequirements` |\n| `scheme` | no | `exact` | Payment scheme. The public facilitator implements `exact`. |\n| `facilitatorURL` | no | `https://x402.org/facilitator` | Base URL of the x402 facilitator |\n| `maxTimeoutSeconds` | no | `60` | Maximum time (seconds) the client has to complete the payment |\n\n¹ `assetName` / `assetVersion` are required by any facilitator implementing the `exact` scheme on EVM — they're embedded in `PaymentRequirements.extra` so the client signs against the correct EIP-712 domain. Omitting them produces an `invalid_exact_evm_missing_eip712_domain` verify error. For non-USDC tokens, read the contract's `name()` and check the source for the EIP-712 version constant.\n\n### Docker labels (Compose / Swarm)\n\n```yaml\nlabels:\n  - \"traefik.enable=true\"\n  - \"traefik.http.routers.paid.rule=Host(`api.example.com`)\"\n  - \"traefik.http.routers.paid.middlewares=x402-pay\"\n  - \"traefik.http.middlewares.x402-pay.plugin.x402.payTo=0xYourWallet\"\n  - \"traefik.http.middlewares.x402-pay.plugin.x402.network=base\"\n  - \"traefik.http.middlewares.x402-pay.plugin.x402.asset=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n  - \"traefik.http.middlewares.x402-pay.plugin.x402.amount=1000\"\n  - \"traefik.http.middlewares.x402-pay.plugin.x402.assetName=USDC\"\n  - \"traefik.http.middlewares.x402-pay.plugin.x402.assetVersion=2\"\n```\n\n### File provider (dynamic config)\n\n```yaml\n# dynamic.yml\nhttp:\n  middlewares:\n    x402-pay:\n      plugin:\n        x402:\n          payTo: \"0xYourWallet\"\n          network: \"base\"\n          asset: \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"  # USDC on Base mainnet\n          amount: \"1000\"\n          assetName: \"USDC\"\n          assetVersion: \"2\"\n          description: \"API access\"\n\n  routers:\n    paid:\n      rule: \"Host(`api.example.com`)\"\n      entryPoints: [web]\n      service: my-upstream@file\n      middlewares: [x402-pay@file]\n```\n\n---\n\n## Compatibility\n\n| Dimension | Supported |\n|---|---|\n| Traefik | v3.7+ (older versions fail against Docker Engine 29's `MinAPIVersion=1.44`) |\n| Networks (public facilitator) | `base`, `base-sepolia` |\n| Default asset | USDC |\n| Plugin runtime dependencies | none (stdlib only) |\n\n---\n\n## Try it locally\n\nA one-command Docker Compose demo with Traefik + a dummy upstream + the plugin loaded via Yaegi is included. See **[docs/dev.md](docs/dev.md)** for the quickstart, the unit / end-to-end test workflow, and troubleshooting.\n\n---\n\n## Roadmap\n\n- Pluggable facilitator selection per-route\n- Prometheus metrics (verify/settle latency, failure rates)\n- Structured JSON logging\n- Response streaming (currently buffered)\n- Payment caching via cookie or JWT to avoid re-verification for the same payer across requests\n- Solana and Stellar network support once public facilitators are available\n\n---\n\n## Contributing\n\nPull requests welcome. See [docs/dev.md](docs/dev.md) for setup, test commands, and dev environment details. Open an [issue](https://github.com/albttx/traefik-plugin-x402/issues) first to discuss non-trivial changes.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Acknowledgements\n\nImplements the [x402 protocol](https://x402.org) designed and specified by [Coinbase](https://github.com/coinbase/x402). The plugin system is provided by [Traefik](https://traefik.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbttx%2Ftraefik-plugin-x402","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbttx%2Ftraefik-plugin-x402","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbttx%2Ftraefik-plugin-x402/lists"}