# AgenticBTC MCP

Govern how AI agents pay and get paid.

AgenticBTC connects MCP-compatible agents to owner-controlled policies, payments, receivables, routing, and verifiable transaction evidence. Owners keep control of credentials and funds.

## Try it safely first

- [Run a no-funds Payment Firewall test](https://agenticbtc.io/payment-firewall?utm_source=npm&utm_medium=package&utm_campaign=mcp-onboarding)
- [Create a free account and API key](https://agenticbtc.io/activate?utm_source=npm&utm_medium=package&utm_campaign=mcp-onboarding)
- [Follow the setup guide](https://agenticbtc.io/activate?utm_source=npm&utm_medium=package&utm_campaign=mcp-onboarding)

The Payment Firewall test requires no account, wallet, signer, or payment credentials. It evaluates a supplied x402 or MCP payment request and returns an allow or block decision plus a downloadable evidence receipt. It does not move funds.

## Requirements

- Node.js 18 or newer
- A free AgenticBTC owner account and API key for hosted tools
- An MCP-compatible client such as OpenClaw or Claude Desktop
- A connected payment rail only when you are ready to execute real payments

## Install and verify with no account

```bash
npx agenticbtc-mcp@latest doctor
```

`doctor` checks Node.js and the public AgenticBTC API. It uses no credentials, wallet, payment rail, or funds.

## Connect your agent

```bash
npx agenticbtc-mcp@latest start
```

The guided setup shows the account-creation URL before asking for an API key. If you exit without a key, it makes no configuration changes.

## Manual MCP configuration

```json
{
  "mcpServers": {
    "agenticbtc": {
      "command": "npx",
      "args": ["-y", "agenticbtc-mcp@latest", "server"],
      "env": {
        "AGENTICBTC_API_URL": "https://agenticbtc.app",
        "AGENTICBTC_API_KEY": "your-owner-api-key"
      }
    }
  }
}
```

Do not commit API keys, wallet credentials, macaroons, or private keys.

## What requires an account

- Public Payment Firewall test: no account, free, no funds
- `doctor` and help: no account, free, no funds
- Saved policies, scoped agent keys, hosted receipts, and connected AgenticBTC tools: free account and API key required
- Real payments: configured owner-controlled rail and available funds required

Installing this package does not grant access to anyone else's funds and does not create or fund a wallet.

## Optional Lightning configuration

Lightning is optional. For an LND-compatible node, set `AGENTICBTC_LND_HOST` and `AGENTICBTC_LND_MACAROON` using credentials scoped to the actions you intend to allow.

## Environment variables

| Variable | Purpose | Default |
|---|---|---|
| `AGENTICBTC_API_URL` | Hosted or self-hosted AgenticBTC API | `https://agenticbtc.app` |
| `AGENTICBTC_API_KEY` | Owner API key | Required for authenticated tools |
| `AGENTICBTC_LND_HOST` | Optional LND REST host | Unset |
| `AGENTICBTC_LND_MACAROON` | Optional LND macaroon | Unset |

Legacy `AGENTBTC_*` variable names remain accepted for compatibility. New setups should use `AGENTICBTC_*`.

## Development

```bash
npm install
npm test
```

```text
bin/agentbtc.js   CLI setup, status, and server launcher
src/server.js     MCP server implementation
package.json      npm package metadata
```

## Security and support

- Security-sensitive reports: `support@agenticbtc.io`
- Documentation: [agenticbtc.io/docs](https://agenticbtc.io/docs)
- Issues: [GitHub Issues](https://github.com/bkblocksolutions-rgb/agenticbtc-mcp/issues)

## License

MIT. See [LICENSE](LICENSE).