dgb-tollgate

DigiDollar paywall proxy for MCP servers — plus an autonomous paying client.

v0.1 is the paywall proxy (src/server.js): it returns HTTP 402 with a DigiDollar invoice and issues bearer tokens after payment. v0.2 is the paying client (src/client.js): a stdio MCP server an AI agent connects to; it detects 402, pays DigiDollar automatically (within spend caps), obtains a token, and mirrors upstream tools — no human in the loop.

TESTNET ONLY — not audited

This is v0.1 research / demo software. Default REQUIRE_TESTNET=true refuses to run against a non-test chain. Do not use on mainnet with real funds. There is no security audit. Expect breaking changes. You run this at your own risk.

Flow (v0.1 tollgate proxy)

Agent                         dgb-tollgate                      Your node / upstream
  |                                |                                   |
  |-- MCP request (no token) ----->|                                   |
  |<- 402 + fresh DD invoice ------|                                   |
  |                                |-- getdigidollaraddress ---------->|
  |                                |                                   |
  |-- pay DigiDollar to payTo --------------------------------------> chain
  |                                |                                   |
  |-- POST /token { invoiceId } -->|                                   |
  |                                |-- listdigidollarutxos (own node) ->|
  |<- { token } -------------------|(only if address balance ≥ price)  |
  |                                |                                   |
  |-- MCP + Authorization: Bearer >|                                   |
  |                                |-- reverse-proxy ----------------->| upstream MCP
  |<- upstream response -----------|<- streamed response --------------|

Flow (v0.2 autonomous loop)

Claude / agent                paying client (stdio)           tollgate (v0.1)        upstream MCP
  |                                |                              |                        |
  |-- MCP stdio ------------------>|                              |                        |
  |                                |-- HTTP MCP (no token) ------>|                        |
  |                                |<- 402 + DD invoice ----------|                        |
  |                                |-- senddigidollar (wallet) ---> node                   |
  |                                |-- POST /token -------------->|                        |
  |                                |<- bearer token ---------------|                        |
  |                                |-- HTTP MCP + Bearer -------->|-- proxy ------------->|
  |<- tool result ------------------|<- upstream response ----------|<-----------------------|

The paying client caches the bearer token until expiry. It only pays again when there is no valid token. Spend caps (DD_MAX_PAYMENT_USD, DD_MAX_DAILY_USD) are enforced before any senddigidollar call.

1. Unpaid request → HTTP 402 with a fresh DigiDollar address and invoice id.
2. Agent pays that address in DigiDollar (minimum $1.00 — consensus floor).
3. POST /token with { "invoiceId" } → tollgate checks its own node (listdigidollarutxos at the invoice address). Client txids are never trusted.
4. On success, a short-lived HMAC-SHA256 bearer token is issued.
5. Requests with a valid Bearer token are reverse-proxied to UPSTREAM_MCP_URL (method, headers, body; streamed response).

Quick start

npm install

# Configure (placeholders only in the repo — use your own secrets locally)
cp .env.example .env   # then edit; do not commit .env

# Terminal A — example upstream MCP (one tool: echo)
npm run upstream

# Terminal B — tollgate (loads env from your shell / dotenv of your choice)
export $(grep -v '^#' .env | xargs)   # or use your preferred env loader
npm start

# Terminal C — v0.1 walkthrough (payment step is manual)
npm run demo

# Or: v0.2 autonomous loop (payment is automatic)
npm run paid-demo

Paying client (v0.2)

Point your MCP host at the stdio server (bin: dgb-tollgate-client):

{
  "mcpServers": {
    "dgb-tollgate-client": {
      "command": "node",
      "args": ["/path/to/dgb-tollgate/src/client.js"],
      "env": {
        "TOLLGATE_URL": "http://127.0.0.1:8080/mcp",
        "TOLLGATE_TOKEN_URL": "http://127.0.0.1:8080/token",
        "DGB_RPC_URL": "http://127.0.0.1:14023",
        "DGB_RPC_USER": "rpcuser",
        "DGB_RPC_PASSWORD": "…",
        "DGB_WALLET": "wallet-name",
        "DD_MAX_PAYMENT_USD": "5",
        "DD_MAX_DAILY_USD": "25"
      }
    }
  }
}

Or: npm run client (with the same env vars exported in your shell).

Config

Tollgate server (v0.1)

| Variable | Required | Default | Description | |---|---|---|---| | UPSTREAM_MCP_URL | yes | — | Streamable-HTTP MCP endpoint to protect | | PRICE_USD | yes | — | Price per token; must be ≥ 1.00 | | TOKEN_TTL_SECONDS | no | 3600 | Bearer token lifetime after payment | | TOLLGATE_SECRET | yes | — | HMAC signing secret (≥ 16 chars) | | DGB_RPC_URL | yes | — | DigiByte Core RPC URL | | DGB_RPC_USER | yes | — | RPC username | | DGB_RPC_PASSWORD | yes | — | RPC password | | DGB_WALLET | yes | — | Wallet name (fresh DD addresses) | | REQUIRE_TESTNET | no | true | Exit unless node chain is test | | PORT | no | 8080 | Tollgate listen port | | INVOICE_TTL_SECONDS | no | 900 | How long an unpaid invoice is valid | | MIN_CONFIRMATIONS | no | 1 | Confirmations required for payment | | MAX_OUTSTANDING_INVOICES | no | 1000 | Cap on unsettled invoices; excess requests get HTTP 429 |

Startup rejects PRICE_USD < 1.00 because DigiDollar cannot create outputs below $1.00.

Paying client (v0.2)

| Variable | Required | Default | Description | |---|---|---|---| | TOLLGATE_URL | yes | — | Paywalled Streamable-HTTP MCP endpoint | | TOLLGATE_TOKEN_URL | yes | — | Tollgate POST /token URL | | DGB_RPC_URL | yes | — | DigiByte Core RPC (wallet that pays) | | DGB_RPC_USER | yes | — | RPC username | | DGB_RPC_PASSWORD | yes | — | RPC password | | DGB_WALLET | yes | — | Wallet name used for senddigidollar | | DD_MAX_PAYMENT_USD | no | 5 | Per-payment spend cap | | DD_MAX_DAILY_USD | no | 25 | Rolling 24h spend cap | | REQUIRE_TESTNET | no | true | Exit unless node chain is test | | PAY_POLL_TIMEOUT_MS | no | 90000 | Max wait for /token after payment | | PAY_POLL_INTERVAL_MS | no | 3000 | Poll interval for /token |

Security model (do not weaken)

• Payment is verified only by querying your DigiByte node for DigiDollar UTXOs at the invoice address. A client-supplied txid is never proof.
• Fresh DigiDollar address per invoice so “paid?” = address balance lookup.
• Bearer tokens are HMAC-SHA256 over { invoiceId, exp }; verification uses a constant-time compare.
• Secrets and tokens are never logged.
• Testnet guard is on by default.
• The paying client enforces spend caps before payment (allowance, not custody).
• senddigidollar always receives integer cents (never decimal dollars).

API surface

| Method | Path | Auth | Behavior | |---|---|---|---| | POST | /token | none | Body { invoiceId } → verify payment → { token, tokenType, expiresAt, invoiceId } | | * | any other | Bearer | Valid token → proxy to upstream; else 402 + new invoice |

Example 402 body

{
  "x402Version": 1,
  "error": "Payment Required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "digibyte-testnet",
      "asset": "DigiDollar",
      "payTo": "<fresh-dd-address>",
      "amountUsd": 1,
      "amountCents": 100,
      "invoiceId": "<uuid>",
      "expiresAt": "2026-01-01T00:15:00.000Z"
    }
  ],
  "hint": "Pay the DigiDollar amount to payTo, then POST /token ..."
}

Layout

src/server.js          v0.1 tollgate proxy (Express)
src/client.js          v0.2 paying MCP client (stdio)
src/payer.js           DigiDollar payment + spend-cap policy
example/upstream-mcp.js   Minimal Streamable-HTTP MCP (tool: echo)
example/demo.sh           v0.1: manual payment walkthrough
example/paid-agent-demo.sh   v0.2: fully autonomous payment demo
reference/           Proven modules from dgb-x402 (source of security model)

Non-goals (v0.1 / v0.2)

• Per-tool pricing (all-or-nothing per token)
• Digi-ID identity gating
• Batch / metered settlement
• stdio→HTTP bridging (upstream must already be HTTP)
• Multi-tenant dashboards or durable persistence

License

MIT