@morebetterclaw/forge-swap

FORGE — Cross-Chain Swap Agent

A production-ready HTTP API for cross-chain token swaps via THORChain. It routes swap quotes and executes transactions through THORNode directly — no centralised exchange, no custodian. Designed for agent-to-agent use: any AI agent or automated system can POST a swap request and receive back the deposit memo and vault address needed to execute on-chain.

Every swap routed through this service collects a 0.5% affiliate fee to a configurable THORChain address, making it a self-sustaining revenue-generating infrastructure component. Fees are embedded directly in the THORChain memo and settled natively by the protocol — no invoicing, no off-chain reconciliation.

Quick Start (local)

git clone <your-repo-url>
cd crypto-swap-agent
cp .env.example .env
# Fill in FEE_RECIPIENT_ADDRESS (your thor1... address)
npm install
npm start
# Server at http://localhost:3000

API Reference

GET /health

Service health check. Used by Railway and uptime monitors.

Response:

{ "status": "ok", "version": "0.1.0", "timestamp": "2026-03-14T00:00:00.000Z" }

POST /swap/quote

Get a swap quote with affiliate fee included.

Request body:

{
  "fromAsset": "ETH.ETH",
  "toAsset": "BTC.BTC",
  "amount": "0.1"
}

Response:

{
  "fromAsset": "ETH.ETH",
  "toAsset": "BTC.BTC",
  "amount": "0.1",
  "expectedOutput": "0.00315",
  "expectedOutputMinusFees": "0.00312",
  "affiliateFee": "0.5%",
  "route": ["THORChain"],
  "slippage": "0.50%",
  "expiresAt": "2026-03-14T00:00:30.000Z"
}

POST /swap/execute

Build swap transaction data. Returns the memo and deposit address for on-chain execution.

Request body:

{
  "fromAsset": "ETH.ETH",
  "toAsset": "BTC.BTC",
  "amount": "0.1",
  "destinationAddress": "bc1q..."
}

Response:

{
  "status": "pending_signature",
  "memo": "=:BTC.BTC:bc1q...:0/3/0:thor1ab12:50",
  "depositAsset": "ETH.ETH",
  "depositAmount": 0.1,
  "depositAddress": "0xTHORVault...",
  "expectedOutput": "0.00312",
  "route": ["THORChain"],
  "affiliateFee": "0.5%",
  "warning": "Wallet signing required — call wallet.sign(swapData) to execute"
}

GET /swap/status?txHash=<hash>

Check the status of a submitted swap transaction via Midgard.

Response: Raw Midgard v2/actions response for the tx.

GET /swap/assets

List all supported assets (THORChain pools via Midgard).

Response: Array of pool/asset objects.

MCP Integration

FORGE exposes a Model Context Protocol server at /mcp using Streamable HTTP transport (2026 spec).

Any MCP-compatible AI agent (Claude, GPT, Cursor, etc.) can discover and call FORGE natively.

Endpoint: POST /mcp Discovery: GET /.well-known/mcp.json

Available tools: forge_quote, forge_execute, forge_assets, forge_status

Claude Desktop config:

{
  "mcpServers": {
    "forge": {
      "url": "https://forge.morebetterstudios.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Why MCP: Enables zero-friction discovery and calling by any frontier AI agent without API key registration or custom integration.

Environment Variables

Variable	Required	Default	Description
FEE_RECIPIENT_ADDRESS	Yes	—	THORChain thor1... address for affiliate fee collection
SWAP_FEE_BPS	No	50	Fee in basis points (50 = 0.5%)
WALLET_PRIVATE_KEY	No	—	EVM private key for autonomous swap execution
EVM_RPC_URL	No	—	Alchemy/Infura RPC URL for EVM signing
PORT	No	3000	HTTP port
NODE_ENV	No	production	Node environment
ALLOWED_ORIGINS	No	*	CORS allowed origins
LOG_LEVEL	No	info	Logging verbosity
RATE_LIMIT_WINDOW_MS	No	60000	Rate limit window in ms
RATE_LIMIT_MAX	No	100	Max requests per window

Deploy to Railway

• Push to GitHub
• Connect repo at railway.app/new
• Set environment variables in Railway Dashboard → Variables

Full Railway deployment guide: deploy/README.md

Revenue Model

Every swap routed through this agent includes a 0.5% affiliate fee (configurable via SWAP_FEE_BPS). The fee address (FEE_RECIPIENT_ADDRESS) must be a valid THORChain thor1... address.

The fee is embedded in the THORChain memo at the protocol level:

=:BTC.BTC:bc1q...:0/3/0:thor1xxxx:50

THORChain nodes enforce and distribute this fee natively — there is no off-chain settlement or trust assumption. At current volumes, each basis point of fee on a $10k swap = $1 in RUNE credited to your address.

Using as an OpenClaw Skill

This service is packaged as an OpenClaw skill. See SKILL.md for the skill definition and invocation instructions.

Cross-Chain Products

Additional trading agent integrations coming soon:

• Vantage HL — Hyperliquid perpetuals trading agent (link TBD)
• Additional DEX/CEX routing integrations (TBD)