# IRL Gateway

> IRL Gateway is a freemium MCP server for finance and payments. Mandate gateway for AI trading agents: checks each order, seals reasoning, binds the fill. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Freemium
- **Platforms:** CLI, API
- **Website:** https://norve.dev
- **Repository:** https://github.com/norve-labs/irl-gateway
- **MCP Registry name:** io.github.norve-labs/irl-gateway
- **Categories:** finance and payments, security
- **Listing updated:** 2026-11-16

## About

A trading agent calls execute_trade with its reasoning. The gateway checks the order against the agent's mandate (active status, notional cap, allowed assets and venues), seals a hash of the rationale into IRL's tamper-evident trace anchored daily to Bitcoin, places a spot market order, and then records whether the fill MATCHED or DIVERGED from what was authorised. The plaintext rationale stays in a local journal.

It fails closed: if IRL is unreachable or denies the intent, no order is sent. Creating the file ~/.irl-gateway/KILL refuses every trade, and order sizes are rounded to the venue's rules before sealing so the sealed quantity is what is sent.

Paper trading is the default, with simulated fills at live public Binance prices and no exchange keys. The README says uvx irl-gateway init issues a free paper-tier token with a starter mandate for BTC/USDT and ETH/USDT up to 1,000 USDT per order, limited to 3 agents and 500 authorizations a day. Live trading means self-hosting the engine or asking for a full token. The site says IRL produces evidence but does not make a firm compliant on its own.

## Features

- **Mandate checks:** Orders are validated against status, caps, assets and venues first.
- **Sealed reasoning:** The rationale is hashed and anchored on Bitcoin.
- **Fill reconciliation:** Each trade is recorded as MATCHED or DIVERGENT.
- **Fail closed:** No order is sent if IRL is unreachable or denies it.
- **Kill switch:** A local KILL file refuses all trades.
- **Paper trading:** Default simulated fills at live Binance prices.

## Good for

- Constrain an AI trading agent to set assets and order sizes
- Keep an auditable record of why each trade was made
- Test a trading agent safely with paper fills
- Export proof for an auditor to verify offline

## Install

### Claude Code (Terminal)

```sh
claude mcp add irl-gateway --env IRL_API_TOKEN='<IRL_API_TOKEN>' -- uvx irl-gateway
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": [
        "irl-gateway"
      ],
      "env": {
        "IRL_API_TOKEN": "<IRL_API_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": [
        "irl-gateway"
      ],
      "env": {
        "IRL_API_TOKEN": "<IRL_API_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "irl-gateway": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "irl-gateway"
      ],
      "env": {
        "IRL_API_TOKEN": "<IRL_API_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": [
        "irl-gateway"
      ],
      "env": {
        "IRL_API_TOKEN": "<IRL_API_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": [
        "irl-gateway"
      ],
      "env": {
        "IRL_API_TOKEN": "<IRL_API_TOKEN>"
      }
    }
  }
}
```

## Tools

- `execute_trade`: Place a spot market order through authorize, place and bind.
- `get_policy`: Show the agent's mandate and kill-switch state.
- `get_quote`: Last price on the gateway's venue.
- `get_balances`: Free balances, paper or exchange.
- `get_trace`: IRL's sealed record of one trade.
- `list_recent_trades`: Local journal of recent trades.

## FAQ

### Does it trade live by default?

No. Paper trading is the default and needs no exchange keys.

### What are the free tier limits?

Paper venues only, up to 3 agents and 500 authorizations a day per token.

### Can it prove the agent told the truth?

No. The site says the agent reports its own reasoning; the scheme proves timing, integrity and binding.

### How do I start?

Run uvx irl-gateway init to get a token and an MCP config line.

### Is IRL Gateway free?

IRL Gateway has a free plan, with paid plans for more usage or features.

### How do I add IRL Gateway to Claude Code?

Run this command in your terminal: claude mcp add irl-gateway --env IRL_API_TOKEN='<IRL_API_TOKEN>' -- uvx irl-gateway

### What are the best alternatives to IRL Gateway?

The closest alternatives to IRL Gateway are REA, Solana MCP by Vybe, Tapetide - Indian Stock Market MCP, Agent Roast and Midplane.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Solana MCP by Vybe](https://ai-powered.com/mcp/solana-mcp-by-vybe): Solana MCP by Vybe is an MCP server for finance and payments.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [Agent Roast](https://ai-powered.com/mcp/agent-roast): Agent Roast is an open-source MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Budget Tracker](https://ai-powered.com/mcp/budget-tracker-2): Budget Tracker is a freemium MCP server for finance and payments.
- [Leash](https://ai-powered.com/mcp/leash): Leash is a free MCP server for security.
- [Tinplate Edge AI Safety, Security & EU Compliance](https://ai-powered.com/mcp/tinplate-edge-ai-safety-security-and-eu-compliance): Tinplate Edge AI Safety, Security & EU Compliance is a freemium MCP server for security.

---
Source: https://ai-powered.com/mcp/irl-gateway
