🔒 local402

Платежный шлюз для AI-агентов одной командой

Превратите любой локальный сервер в платный ресурс за секунды. Идеально для тестирования агентов, которым нужно платить за доступ к вашему API или MCP-инструменту.

npx local402 --target http://localhost:3000 --price 0.001

Что это такое?

local402 устанавливает x402-стиль HTTP 402 Payment Required перед любым локальным HTTP-сервером или MCP-инструментом — одной командой, без настройки и без блокчейна.

Запросы без оплаты получают чистый 402. Запросы, которые «платят», проксируются напрямую к вашему реальному серверу. Вот и всё.

По умолчанию он работает в полностью симулированном режиме: без кошельков, без газа, без внешних сервисов, без ожидания. Просто мгновенные, детерминированные 402-ответы для локальной разработки и тестирования.

agent ──▶  local402 (402 paywall)  ──▶  your server
             │
             └── no payment? → 402 Payment Required
                 paid?       → proxied response ✅

Related MCP server: x402 MCP Proxy

💸 Зачем нужен local402?

Агенты учатся платить за вещи — вызовы API, выполнение инструментов, данные, вычисления. Протокол x402 делает нативные платежи через HTTP реальностью. Но есть проблема:

Как тестировать платящего агента без траты реальных денег, создания кошелька или подключения целого платежного стека — каждый раз?

Вам не нужно разворачивать фасилитатора и пополнять тестовый кошелек только для того, чтобы проверить, заметил ли ваш агент 402 и повторил ли запрос с оплатой. Вам нужен платежный шлюз, который можно поднять одной командой и так же быстро убрать.

Это local402.

Используйте это для:

• ✅ Тестирования, что ваш AI-агент обрабатывает 402 и повторяет запрос с заголовком x-payment

• ✅ Демонстрации API или MCP-инструмента с оплатой за вызов без касания блокчейна

• ✅ Разработки клиентской логики x402 офлайн, в самолете, в CI

• ✅ Прототипирования ценовой политики перед переходом на реальные расчеты

⚡ Быстрый старт

Вам даже не нужно его устанавливать.

# 1. Have any local server running (your API, MCP tool, whatever)
#    e.g. something on http://localhost:3000

# 2. Put a paywall in front of it
npx local402 --target http://localhost:3000 --price 0.001

local402 теперь слушает на http://localhost:4020 и защищает ваш сервер.

# ❌ No payment → 402 Payment Required
curl -i http://localhost:4020/

# ✅ "Pay" → request is proxied to your real server
curl -i http://localhost:4020/ -H "x-payment: simulated"

Направьте своего агента на http://localhost:4020 вместо вашего реального сервера и наблюдайте, как он учится платить. 🎉

🛠 Использование

local402 --target <url> [options]

Правило

• Без заголовка x-payment → 402 Payment Required (с информативным JSON-телом + заголовками).

• С заголовком x-payment: simulated (или paid) → запрос проксируется на --target, и реальный ответ возвращается без изменений.

В режиме симуляции принимается любое непустое значение x-payment — simulated и paid — просто канонические варианты.

Примеры

# Guard an MCP tool on a custom port, charge 0.01
local402 --target http://localhost:8787 --port 9000 --price 0.01

# Free status check — always open, never paywalled
curl http://localhost:4020/__local402

🔍 Как это работает

local402 — это крошечный реверс-прокси с одним принципом: сначала плати, затем пропускай.

                        ┌──────────────────────────────┐
                        │           local402            │
                        │        :4020 (paywall)        │
   ┌─────────┐          │                               │          ┌──────────────┐
   │  agent  │ ───────▶ │  x-payment header present?    │          │ your server  │
   │ / curl  │          │                               │          │  :3000       │
   └─────────┘          │   NO  ─▶ 402 Payment Required │          └──────────────┘
        ▲               │                               │                 ▲
        │               │   YES ─▶ proxy the request  ──┼─────────────────┘
        │               │         return real response  │                 │
        └───────────────┤◀──────────────────────────────┼─────────────────┘
              402 or proxied response                    │
                        └──────────────────────────────┘

Ответ без оплаты (HTTP 402):

{
  "x402Version": 1,
  "error": "Payment Required",
  "message": "This resource costs 0.001 USD. Retry with header 'x-payment: simulated'.",
  "accepts": [
    {
      "scheme": "simulated",
      "network": "local",
      "maxAmountRequired": "0.001",
      "asset": "USD",
      "payTo": "local402-simulated",
      "resource": "/",
      "description": "local402 simulated paywall",
      "mimeType": "application/json"
    }
  ],
  "hint": "x-payment: simulated"
}

Заголовки ответа при 402:

HTTP/1.1 402 Payment Required
x-payment-required: true
x-payment-amount: 0.001
x-payment-asset: USD
x-payment-network: local
accept-payment: x-payment: simulated

При оплаченном запросе local402 добавляет симулированную квитанцию о расчете, чтобы ваш клиент мог проверить поток end-to-end:

x-payment-response: <base64 JSON receipt with a sim txHash>

🗺 План развития

local402 изначально простой по замыслу. План:

• v0.1 — Режим симуляции. Мгновенный, локальный, безблокчейн-платежный шлюз 402. (вы здесь)

• v0.2 — Реальный расчет x402. Проверка фактических полезных нагрузок X-PAYMENT через подключаемого фасилитатора.

• v0.3 — Режим MCP. Первоклассный платежный шлюз для MCP-инструментов/ресурсов, а не только HTTP.

• v0.4 — Ценообразование по маршрутам. Разные цены для разных путей и методов.

• v0.5 — Панель использования. Живой TUI-интерфейс запросов, платежей и дохода.

Хотите повлиять на направление? Откройте issue.

🤝 Участие

Приветствуются любые вклады, идеи и сообщения об ошибках — это дружественный маленький инструмент.

git clone https://github.com/wushu75/local402.git
cd local402
npm install
npm run dev -- --target http://localhost:3000   # run from source
npm run build                                    # compile to dist/

1. Форкните 🍴

2. Создайте ветку (git checkout -b feat/удивительная-штука)

3. Зафиксируйте изменения (git commit -m 'feat: удивительная штука')

4. Отправьте и откройте PR

Нет слишком маленьких вкладов — даже исправление опечатки помогает.

📄 Лицензия

MIT © участники local402. Делайте с ним всё, что хотите.

⭐ Поставьте звезду репозиторию, если это полезно

Если local402 избавил вас от необходимости разворачивать платежный стек только для тестирования агента, поставьте звезду — это действительно помогает другим людям найти его.

⭐ Поставить звезду local402 на GitHub

Создано для агентов, которые платят за свой путь. 🔒