@morebetterclaw/forge-swap 0.1.1

package/.env.example

@@ -0,0 +1,21 @@
+# ─── Affiliate Fee (revenue) ──────────────────────────────
+# THORChain RUNE address (starts with thor1...) where 0.5% fees land
+FEE_RECIPIENT_ADDRESS=thor1your_address_here
+# Fee in basis points (50 = 0.5%)
+SWAP_FEE_BPS=50
+
+# ─── Wallet (optional — for autonomous EVM execution) ─────
+# Only needed if agent will execute swaps autonomously
+# Leave blank for quote-only mode (safe for most deployments)
+WALLET_PRIVATE_KEY=
+EVM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your_key_here
+
+# ─── Server ───────────────────────────────────────────────
+PORT=3000
+NODE_ENV=production
+ALLOWED_ORIGINS=*
+LOG_LEVEL=info
+
+# ─── Rate Limiting ────────────────────────────────────────
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100

package/.env.railway

@@ -0,0 +1,24 @@
+# FORGE — Railway Environment Variables
+# Set these in Railway Dashboard → Variables tab
+# Do NOT commit this file with real values
+
+NODE_ENV=production
+PORT=3000
+
+# ── THORChain Affiliate Fee (REQUIRED) ────────────────────
+# Your RUNE address — all 0.5% swap fees land here automatically
+FEE_RECIPIENT_ADDRESS=thor1yfrfgjgnzkjqqgv02yxn3j3kv50pe0rnhvs8zw
+SWAP_FEE_BPS=50
+
+# ── Rate Limiting ──────────────────────────────────────────
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+
+# ── CORS ──────────────────────────────────────────────────
+# Set to your domain when website is live:
+# ALLOWED_ORIGINS=https://morebetterstudios.com,https://www.morebetterstudios.com
+ALLOWED_ORIGINS=*
+
+# ── Optional: Autonomous EVM execution (v2 — leave blank for launch) ──
+# WALLET_PRIVATE_KEY=
+# EVM_RPC_URL=

package/.mcpregistry_github_token

@@ -0,0 +1 @@
+ghu_AMjMT6Ldr8d2xMEGzuRJmFUkO9NrhT4eoByt

package/.mcpregistry_registry_token

@@ -0,0 +1 @@
+{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzQxOTQ1ODQsIm5iZiI6MTc3NDE5NDI4NCwiaWF0IjoxNzc0MTk0Mjg0LCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6Im1vcmViZXR0ZXJjbGF3IiwicGVybWlzc2lvbnMiOlt7ImFjdGlvbiI6InB1Ymxpc2giLCJyZXNvdXJjZSI6ImlvLmdpdGh1Yi5tb3JlYmV0dGVyY2xhdy8qIn1dfQ.USQmdeIYcgMQliAgOtfT1VwLtNMpAV_V0NEWyyhHIKhjQxEqlqOOx7Wx66OKZe0a7_OHt1XXJLg5dtGNheOdAw","expires_at":1774194584}

package/BUILD_BRIEF_V1.md

@@ -0,0 +1,216 @@
+# Crypto Swap Agent — Build Brief v1
+**Issued by:** Daksh (CEO, MoreBetter Studios)
+**Date:** 2026-03-14
+**Priority:** HIGH
+**Estimated scope:** 3–4 hours
+
+---
+
+## Context
+
+The `crypto-swap-agent` project exists and has a working SwapKit REST client (`src/swapkit.js`), wallet signing layer (`src/wallet.js`), command parser (`src/parser.js`), and formatter (`src/formatter.js`). However it is incomplete — it is currently a CLI only, and cannot be deployed as an always-on web service. This brief covers everything needed to make it production-deployable.
+
+---
+
+## What Exists (do not rewrite these)
+
+- `src/swapkit.js` — SwapKit REST API client, affiliate fee injection ✅
+- `src/wallet.js` — EVM signing + BTC deposit instructions ✅
+- `src/parser.js` — natural language command parser ✅
+- `src/formatter.js` — response formatters ✅
+- `src/health.js` — Express router with GET /health (has module system conflict — fix in place)
+- `deploy/README.md` — Railway deployment guide ✅
+- `SKILL.md` — OpenClaw skill wrapper ✅
+
+---
+
+## Task List
+
+### Task 1 — Fix module system conflict (BLOCKING)
+
+`package.json` declares `"type": "module"` (ESM) but `health.js` uses CommonJS `require()`. This will crash on start.
+
+**Fix:** Convert `health.js` to ESM:
+```js
+// Replace: const { Router } = require('express');
+import { Router } from 'express';
+// Replace: module.exports = router;
+export default router;
+```
+
+Also audit `src/wallet.js` — it mixes `import` (ESM) with some patterns that may cause issues; ensure it is pure ESM.
+
+---
+
+### Task 2 — Build the HTTP server (BLOCKING for deployment)
+
+Create `src/server.js` — an Express HTTP service that exposes the swap agent as an API. This is the core missing piece.
+
+**Required endpoints:**
+
+```
+GET  /health         → { status: "ok", version, timestamp }
+POST /swap/quote     → get a swap quote
+POST /swap/execute   → build + return swap transaction data
+GET  /swap/status    → check swap status by txHash
+GET  /swap/assets    → list supported assets
+```
+
+**POST /swap/quote body:**
+```json
+{
+  "fromAsset": "ETH.ETH",
+  "toAsset": "BTC.BTC",
+  "amount": "0.1"
+}
+```
+
+**POST /swap/quote response:**
+```json
+{
+  "fromAsset": "ETH.ETH",
+  "toAsset": "BTC.BTC",
+  "amount": "0.1",
+  "expectedOutput": "0.00312",
+  "expectedOutputMinusFees": "0.00308",
+  "affiliateFee": "0.5%",
+  "route": ["THORChain"],
+  "slippage": "0.5%",
+  "expiresAt": "<ISO timestamp>"
+}
+```
+
+**POST /swap/execute body:**
+```json
+{
+  "fromAsset": "ETH.ETH",
+  "toAsset": "BTC.BTC",
+  "amount": "0.1",
+  "destinationAddress": "bc1q..."
+}
+```
+
+**POST /swap/execute response:** return the full `swapData` object from `SwapKitApi.executeSwap()` — includes `memo`, `depositAddress`, `expectedOutput`, `affiliateFee`.
+
+**Server requirements:**
+- Use `express` (add to dependencies)
+- Rate limiting: 100 requests per 60s window (use `express-rate-limit`)
+- CORS: allow `process.env.ALLOWED_ORIGINS || '*'`
+- Port: `process.env.PORT || 3000`
+- Error handling middleware: catch errors, return `{ error: message }` with appropriate HTTP status
+- Request logging: log method, path, status, duration (use `console.log` — no extra deps)
+- Graceful shutdown on SIGTERM (for Railway)
+
+**Add `express` and `express-rate-limit` to `package.json` dependencies.**
+
+---
+
+### Task 3 — Update `src/index.js` to be the entry point for the HTTP server
+
+Currently `index.js` is a CLI. Change it so:
+- When run as `node src/index.js` → starts the HTTP server (calls `server.js`)
+- CLI commands are kept as `node src/index.js <command>` for local testing
+- Add a check: if `process.argv[2]` is a recognised command → run CLI mode; otherwise → start server
+
+---
+
+### Task 4 — Create `.env.example`
+
+```bash
+# ─── SwapKit ──────────────────────────────────────────────
+SWAPKIT_API_KEY=your_swapkit_api_key_here
+
+# ─── Affiliate Fee (revenue) ──────────────────────────────
+# THORChain RUNE address (starts with thor1...) where 0.5% fees land
+FEE_RECIPIENT_ADDRESS=thor1your_address_here
+# Fee in basis points (50 = 0.5%)
+SWAP_FEE_BPS=50
+
+# ─── Wallet (optional — for autonomous EVM execution) ─────
+# Only needed if agent will execute swaps autonomously
+# Leave blank for quote-only mode (safe for most deployments)
+WALLET_PRIVATE_KEY=
+EVM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your_key_here
+
+# ─── Server ───────────────────────────────────────────────
+PORT=3000
+NODE_ENV=production
+ALLOWED_ORIGINS=*
+LOG_LEVEL=info
+
+# ─── Rate Limiting ────────────────────────────────────────
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+```
+
+---
+
+### Task 5 — Write a `src/test.js` smoke test
+
+Simple script that:
+1. Starts the server on port 3001
+2. Makes a `GET /health` request — asserts 200 + `{ status: "ok" }`
+3. Makes a `POST /swap/assets` request — asserts array of assets returned
+4. Makes a `POST /swap/quote` with `{ fromAsset: "ETH.ETH", toAsset: "BTC.BTC", amount: "0.1" }` — asserts response has `expectedOutput`
+5. Stops the server
+6. Prints PASS/FAIL for each check
+
+No external test framework — plain Node with `assert`.
+
+---
+
+### Task 6 — Update `README.md` (product-grade)
+
+The existing README is in `deploy/README.md` (Railway guide only). Create a top-level `README.md` with:
+
+1. **What it does** — 2-paragraph product description; mention THORChain routing, affiliate fee model, agent-to-agent use case
+2. **Quick start** (local):
+   ```bash
+   git clone ...
+   cd crypto-swap-agent
+   cp .env.example .env
+   # Fill in SWAPKIT_API_KEY and FEE_RECIPIENT_ADDRESS
+   npm install
+   npm start
+   # Server at http://localhost:3000
+   ```
+3. **API reference** — table of endpoints with example request/response
+4. **Environment variables** — table (copy from .env.example)
+5. **Deploy to Railway** — 3-line summary with link to `deploy/README.md`
+6. **Revenue model** — explain the 0.5% affiliate fee mechanism
+7. **Using as an OpenClaw skill** — point to SKILL.md
+8. **Cross-chain products** — placeholder section with links TBD (for future: Vantage HL trading agent link)
+
+---
+
+## What NOT to do
+
+- Do NOT rewrite `swapkit.js`, `wallet.js`, `parser.js`, or `formatter.js`
+- Do NOT add a database or any stateful storage
+- Do NOT add authentication/API keys for callers (v2 scope)
+- Do NOT implement x402 (v2 scope)
+- Do NOT remove the `deploy/README.md` (keep the Railway guide)
+- Do NOT hardcode any MoreBetter agent names in user-facing output
+
+---
+
+## Output Required
+
+When complete, confirm:
+1. `npm start` → server starts, `/health` returns 200
+2. `npm test` → all smoke tests pass (needs real SWAPKIT_API_KEY to test quote)
+3. List all files created or modified with brief description
+
+Then update your workspace memory with what was done.
+
+---
+
+## Keys (to be filled in by Daksh after SreeMaan provides them)
+
+```
+SWAPKIT_API_KEY=       ← pending SreeMaan
+FEE_RECIPIENT_ADDRESS= ← pending SreeMaan (thor1... address)
+EVM_RPC_URL=           ← pending SreeMaan (Alchemy)
+```
+
+Product name: **TBD** — SreeMaan choosing. Update `package.json` name and README title when confirmed.

package/README.md

@@ -0,0 +1,189 @@
+# 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)
+
+```bash
+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:**
+```json
+{ "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:**
+```json
+{
+  "fromAsset": "ETH.ETH",
+  "toAsset": "BTC.BTC",
+  "amount": "0.1"
+}
+```
+
+**Response:**
+```json
+{
+  "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:**
+```json
+{
+  "fromAsset": "ETH.ETH",
+  "toAsset": "BTC.BTC",
+  "amount": "0.1",
+  "destinationAddress": "bc1q..."
+}
+```
+
+**Response:**
+```json
+{
+  "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](https://modelcontextprotocol.io) 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:**
+```json
+{
+  "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
+
+1. Push to GitHub
+2. Connect repo at [railway.app/new](https://railway.app/new)
+3. Set environment variables in Railway Dashboard → Variables
+
+Full Railway deployment guide: [deploy/README.md](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](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)

package/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: forge
+description: Cross-chain swap routing via THORChain. Get quotes and build swap transactions across 44+ assets (BTC, ETH, RUNE, AVAX, USDC and more). Non-custodial — returns vault address and memo, user's wallet executes. 0.5% affiliate fee to forgemb on every routed swap.
+version: 0.1.0
+author: MoreBetter Studios
+homepage: https://morebetterstudios.com
+repository: https://github.com/morebetterclaw/forge
+api: https://forge-api-production-50de.up.railway.app
+mcp: https://forge-api-production-50de.up.railway.app/mcp
+tags:
+  - crypto
+  - defi
+  - thorchain
+  - swap
+  - cross-chain
+  - bitcoin
+  - ethereum
+  - rune
+---
+
+# FORGE — Cross-Chain Swap Agent
+
+Non-custodial cross-chain swaps powered by THORChain. Routes quotes across 44+ assets via the THORNode API directly. Every swap embeds a 0.5% affiliate fee to `forgemb` — protocol-native, trustless, settled in RUNE.
+
+## Live API
+
+```
+Base:      https://forge-api-production-50de.up.railway.app
+MCP:       https://forge-api-production-50de.up.railway.app/mcp
+Discovery: https://forge-api-production-50de.up.railway.app/.well-known/mcp.json
+```
+
+## MCP Tools (Claude Desktop / Cursor / any MCP client)
+
+```json
+{
+  "mcpServers": {
+    "forge": {
+      "url": "https://forge-api-production-50de.up.railway.app/mcp",
+      "transport": "streamable-http"
+    }
+  }
+}
+```
+
+**Tools:** `forge_quote` · `forge_execute` · `forge_assets` · `forge_status`
+
+## REST API
+
+```bash
+# Get a quote
+curl -X POST https://forge-api-production-50de.up.railway.app/swap/quote \
+  -H "Content-Type: application/json" \
+  -d '{"fromAsset":"ETH.ETH","toAsset":"BTC.BTC","amount":"0.1"}'
+
+# Build swap transaction (returns vault address + memo — no funds sent)
+curl -X POST https://forge-api-production-50de.up.railway.app/swap/execute \
+  -H "Content-Type: application/json" \
+  -d '{"fromAsset":"ETH.ETH","toAsset":"THOR.RUNE","amount":"0.05","destinationAddress":"thor1..."}'
+
+# List supported assets
+curl https://forge-api-production-50de.up.railway.app/swap/assets
+```
+
+## How It Works
+
+1. Call `/swap/execute` with from/to asset and destination address
+2. FORGE returns a **vault deposit address** and **THORChain memo**
+3. User's wallet sends funds to vault address with memo as calldata
+4. THORChain protocol routes the swap — FORGE never holds funds
+5. `forgemb` earns 0.5% affiliate fee embedded in the memo, settled natively
+
+## Asset Format
+
+Assets use `CHAIN.TICKER` format:
+- `ETH.ETH` — Ethereum native
+- `BTC.BTC` — Bitcoin
+- `THOR.RUNE` — THORChain native
+- `AVAX.AVAX` — Avalanche native
+- `ETH.USDC-0xA0b86...` — ERC-20 tokens include contract address
+
+## Environment Variables (self-hosted)
+
+```bash
+FEE_RECIPIENT_ADDRESS=forgemb   # THORName or thor1... address for affiliate fees
+SWAP_FEE_BPS=50                 # 50 = 0.5%
+PORT=3000
+ALLOWED_ORIGINS=*
+```
+
+## Revenue Model
+
+Every swap routed through FORGE earns 0.5% to `forgemb` (THORChain name for `thor1yfrfgjgnzkjqqgv02yxn3j3kv50pe0rnhvs8zw`). Fees are embedded in the THORChain memo and settled by the protocol — no invoicing, no off-chain reconciliation.