dgb-digidollar-mcp

⚠️ TESTNET ONLY — PROOF OF CONCEPT. This is experimental software for the DigiByte testnet. It moves no real money and is not audited. Do not point it at mainnet or a wallet holding real funds. The testnet-only guard is on by default.

An MCP server that lets an AI agent (Claude, etc.) pay for a service in DigiDollar — DigiByte's collateral-backed, USD-denominated stablecoin — following the x402 pay-and-retry pattern:

1. Agent requests a service → service replies 402 Payment Required with a DigiDollar address + price.
2. Agent calls pay_invoice → this server checks the operator's spend policy, then pays.
3. Agent calls payment_status → confirms the tx landed, then retries the request.

The agent never holds keys. The wallet and the spend caps live here, on the operator's machine. Allowance, not custody.

Why DigiDollar, and why this settles the "did I get paid in DD?" question

Agent payments need stable pricing — nobody wants an API call that costs 30% more because the token moved. That's why the rest of the agent economy settles in USDC. But USDC has an issuer-level blacklist, and Base has a single sequencer: two kill switches. DigiDollar has neither — it's minted against locked DGB collateral on a proof-of-work L1, with no freeze function in the protocol.

DGB secures it. DigiDollar spends it.

The obvious worry for a merchant is: "how do I know I was paid in DigiDollar and not just bare DGB sent to the same address?" It turns out the protocol makes that impossible by construction:

• DigiDollar has its own address type (DD / TD / RD prefix), distinct from dgb1…/dgbt1….
• It has its own UTXO set (listdigidollarutxos, getdigidollarbalance).
• A plain DGB address fails validateddaddress outright — this server refuses to send to one.

So DD and DGB cannot be confused. A merchant checking getdigidollarbalance / listdigidollarutxos is, by definition, seeing DigiDollar.

Amounts, one sharp edge worth knowing: senddigidollar reads an integer as cents but a decimal as dollars (10000 = $100, 10000.00 = $10,000). This server always converts to integer cents internally so that 100x foot-gun can't fire.

Architecture

Your machine                               Your node host
┌─────────────────────────┐                ┌──────────────────────────┐
│ Claude ── MCP server ───┼── SSH tunnel ──┼─> digibyted (testnet26)  │
│           (this repo)   │  :14026        │   RPC 127.0.0.1:14026    │
└─────────────────────────┘                └──────────────────────────┘

The node's RPC is bound to localhost on the node host and never exposed to the internet. tunnel.sh forwards a local port to it over SSH (key-only auth recommended). If you run the node on the same machine as the MCP server, you can skip the tunnel and point DGB_RPC_URL straight at the local node.

Try it yourself

You provide your own node and your own keys — that's the point. Nothing here is hosted; there is no shared server to trust.

1. Run a DigiByte DigiDollar testnet node. Install DigiByte Core v9.26.4+ and start it on testnet with RPC enabled. Minimal digibyte.conf:

testnet=1
server=1
[test]
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcuser=YOUR_RPC_USER
rpcpassword=YOUR_STRONG_RPC_PASSWORD

Let it sync testnet26 (the DigiDollar test network). Confirm with digibyte-cli -datadir=... getblockchaininfo → "chain": "test".

2. Create a wallet and get some testnet DGB.

digibyte-cli -datadir=... createwallet mcp-sandbox
digibyte-cli -datadir=... -rpcwallet=mcp-sandbox getnewaddress

Paste that address into the DigiByte testnet faucet and it'll send you free tDGB. (Testnet coins are worthless by design — they exist so you can build and break things without risking anything.)

3. Mint some DigiDollar. DD doesn't exist until someone locks DGB collateral to create it. Check what you'd need, then mint:

# what collateral does $100 of DD cost at lock tier 0 (1 hour)?
digibyte-cli -datadir=... -rpcwallet=mcp-sandbox estimatecollateral 10000 0

# mint $100 (amount is in CENTS; tier 0 = 1h lock, tiers run 0-9 up to 10 years)
digibyte-cli -datadir=... -rpcwallet=mcp-sandbox mintdigidollar 10000 0

Heads-up: the short tiers are heavily over-collateralised (tier 0 is ~1000%), so $100 of DD locks roughly 390,000 tDGB at current prices. Longer locks need less. The faucet won't give you that much in one go — either claim over a few days, ask in the DigiByte community, or use a longer lock tier.

4. Configure and self-test.

npm install
cp .env.example .env      # fill in your RPC user/password (+ SSH host if remote)
./tunnel.sh &             # only if the node is on another host; leave running
npm run smoke             # connectivity + policy self-test — moves no funds

5. Connect it to Claude. Add the server to your MCP client config (see claude-config-snippet.json, with the paths adjusted to where you cloned this). Then ask the agent to check the balance and pay a small testnet invoice. Watch the policy layer block anything over your caps.

Tools

Tool	What it does
check_balance	DigiDollar balance (USD) + DGB balance + node sync + current policy state.
pay_invoice	Send amountUsd of DigiDollar to a DD address, subject to policy. Returns txid.
pay_invoice_dgb	Secondary path: pay in plain DGB instead. Separate caps.
payment_status	Confirmation count for a txid (the x402 retry gate).

Safety policy (.env)

• DGB_REQUIRE_TESTNET=true — server refuses to run unless the node reports chain=test.
• DD_MAX_PAYMENT_USD / DD_MAX_DAILY_USD — DigiDollar caps, in US dollars.
• DGB_MAX_PAYMENT / DGB_MAX_DAILY — separate caps for the raw-DGB path.

DigiDollar and DGB get separate ledgers and separate caps — a dollar and a DGB are not interchangeable units, so they are never netted against each other.

Roadmap

• [x] Milestone 1 — pay in plain testnet DGB (sendtoaddress).
• [x] Milestone 2 — pay in DigiDollar (senddigidollar), USD-denominated, with DD-address validation. Proven live on testnet26.
• [ ] Milestone 3 — a 402 merchant library: emit invoices, watch for DD payment, ship on confirm.
• [ ] Milestone 4 — publish to the MCP registry.

Help wanted

Milestone 3 is where collaboration is most welcome: the merchant side. A drop-in library so any service can emit a 402 Payment Required with a DigiDollar invoice, watch for the payment, and deliver on confirmation. Issues and PRs welcome.

Status

Proven live on testnet26 — an AI agent paid $2.50 and $1.25 in DigiDollar to a merchant wallet (confirmed on-chain), while the policy layer correctly blocked a payment over the cap and refused to send DigiDollar to a bare DGB address.

This is a rough proof of concept, not production software. It should never touch mainnet or real funds.

Built for the DigiByte community. Testnet only. Not financial software.