@morebetterclaw/forge-swap 0.1.1

package/deploy/README.md

@@ -0,0 +1,156 @@
+# Deploying crypto-swap-agent to Railway.app
+
+> Week 2 deployment guide — Railway.app setup, environment configuration, and monitoring.
+
+---
+
+## Prerequisites
+
+- [Railway CLI](https://docs.railway.app/develop/cli) installed: `npm install -g @railway/cli`
+- Railway account: [railway.app](https://railway.app)
+- Project code pushed to GitHub or available locally
+
+---
+
+## Quick Deploy
+
+### Option A — GitHub (recommended)
+
+1. Go to [railway.app/new](https://railway.app/new)
+2. Select **"Deploy from GitHub repo"**
+3. Authorise Railway and choose the `crypto-swap-agent` repo
+4. Railway auto-detects Node.js and sets the build command
+5. Add environment variables (see table below)
+6. Click **Deploy**
+
+### Option B — Railway CLI
+
+```bash
+# Install CLI
+npm install -g @railway/cli
+
+# Login
+railway login
+
+# Initialise project (from project root)
+railway init
+
+# Deploy
+railway up
+
+# Open service URL
+railway open
+```
+
+---
+
+## Environment Variables
+
+Set these in Railway Dashboard → **Variables** tab, or via `railway variables set KEY=VALUE`.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `NODE_ENV` | Yes | `production` | Node environment |
+| `PORT` | No | `3000` | Port (Railway injects this automatically) |
+| `THORNODE_URL` | Yes | `https://thornode.ninerealms.com` | THORNode API endpoint |
+| `LOG_LEVEL` | No | `info` | Logging verbosity (`debug`, `info`, `warn`, `error`) |
+| `RATE_LIMIT_WINDOW_MS` | No | `60000` | Rate limit window in ms |
+| `RATE_LIMIT_MAX` | No | `100` | Max requests per window |
+| `ALLOWED_ORIGINS` | No | `*` | CORS allowed origins (comma-separated) |
+
+> **Never set private keys or wallet secrets in Railway environment variables** unless using Railway's encrypted secrets feature. Prefer a secrets manager (e.g. Doppler, HashiCorp Vault) for sensitive values.
+
+---
+
+## Health Check Configuration
+
+Railway uses the `/health` endpoint to determine service availability.
+
+In Railway Dashboard → **Settings** → **Health Check**:
+
+```
+Path:    /health
+Timeout: 10s
+```
+
+The endpoint returns:
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "timestamp": "2025-03-09T23:00:00.000Z"
+}
+```
+
+Railway will restart the service if this endpoint returns a non-200 status.
+
+---
+
+## Custom Domain
+
+1. Dashboard → **Settings** → **Domains**
+2. Click **Generate Domain** for a `*.railway.app` subdomain, OR
+3. Click **Custom Domain** and add your CNAME record
+
+---
+
+## Monitoring
+
+### Railway Built-in Metrics
+
+Railway Dashboard provides:
+- CPU and memory usage graphs
+- Request logs (stream via `railway logs --tail`)
+- Deployment history and rollback
+
+### External Uptime Monitoring (recommended)
+
+| Tool | Free tier | Setup |
+|---|---|---|
+| [UptimeRobot](https://uptimerobot.com) | 50 monitors, 5-min checks | Add `GET https://<your-domain>/health` |
+| [Betterstack](https://betterstack.com/uptime) | 10 monitors, 3-min checks | Add HTTP monitor for `/health` |
+| [Cronitor](https://cronitor.io) | 5 monitors | Monitor URL + alert on non-200 |
+
+### Log Streaming
+
+```bash
+# Tail live logs
+railway logs --tail
+
+# Filter for errors
+railway logs --tail | grep ERROR
+```
+
+---
+
+## Scaling
+
+Railway supports vertical scaling (memory/CPU) per service:
+
+- Dashboard → **Settings** → **Resources**
+- Recommended starting config: **512 MB RAM, 0.5 vCPU**
+- Scale up if handling high quote volume or running background scan loops
+
+---
+
+## Rollback
+
+```bash
+# List recent deployments
+railway deployments list
+
+# Roll back to a specific deployment
+railway deployments rollback <deployment-id>
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| Build fails | Check `package.json` `engines.node` matches Railway's Node version |
+| Health check failing | Verify `/health` route is mounted before auth middleware |
+| Port not bound | Ensure `app.listen(process.env.PORT \|\| 3000)` — Railway injects `PORT` |
+| Missing env vars | Check Railway Variables tab; redeploy after adding new vars |
+| Memory OOM | Increase RAM in Railway Resources settings |

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@morebetterclaw/forge-swap",
+  "version": "0.1.1",
+  "description": "FORGE — cross-chain swap agent powered by THORChain. Protocol-native routing with embedded affiliate fees.",
+  "main": "src/index.js",
+  "type": "module",
+  "mcpName": "io.github.morebetterclaw/forge-swap",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "telegram": "node src/telegram.js",
+    "test": "node src/test.js",
+    "test:api": "node src/test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^16.4.1",
+    "ethers": "^6.16.0",
+    "express": "^4.18.2",
+    "express-rate-limit": "^7.2.0"
+  },
+  "optionalDependencies": {
+    "node-telegram-bot-api": "^0.64.0"
+  },
+  "keywords": [
+    "openclaw",
+    "thorchain",
+    "swapkit",
+    "defi",
+    "swap",
+    "mcp",
+    "cross-chain"
+  ],
+  "author": "MoreBetter Studios",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morebetterclaw/forge.git"
+  }
+}

package/public/mcp.json

@@ -0,0 +1,10 @@
+{
+  "name": "FORGE",
+  "version": "0.1.0",
+  "description": "Cross-chain swap routing via THORChain. Non-custodial, protocol-native affiliate fee model.",
+  "url": "https://forge-api-production-50de.up.railway.app/mcp",
+  "transport": "streamable-http",
+  "tools": ["forge_quote", "forge_execute", "forge_assets", "forge_status"],
+  "contact": "https://morebetterstudios.com",
+  "license": "MIT"
+}

package/railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.app/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "node src/index.js",
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 30,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 3
+  }
+}

package/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.morebetterclaw/forge-swap",
+  "description": "FORGE Swap — cross-chain swaps via THORChain. Quote and execute BTC, ETH, RUNE, USDC swaps.",
+  "repository": {
+    "url": "https://github.com/morebetterclaw/forge",
+    "source": "github"
+  },
+  "version": "0.1.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@morebetterclaw/forge-swap",
+      "version": "0.1.1",
+      "transport": {
+        "type": "streamable-http",
+        "url": "https://forge-api-production-50de.up.railway.app/mcp"
+      }
+    }
+  ]
+}

package/setup-check.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * setup-check.js — Crypto Swap Agent pre-flight check
+ * Run: node setup-check.js
+ * 
+ * Verifies all required env vars and connectivity before deployment.
+ */
+
+import 'dotenv/config';
+import https from 'https';
+
+const RED   = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+
+let pass = 0, warn = 0, fail = 0;
+
+function check(label, condition, hint = '', severity = 'fail') {
+  if (condition) {
+    console.log(`${GREEN}  ✓${RESET}  ${label}`);
+    pass++;
+  } else {
+    const icon = severity === 'warn' ? `${YELLOW}  ⚠${RESET}` : `${RED}  ✗${RESET}`;
+    console.log(`${icon}  ${label}`);
+    if (hint) console.log(`       → ${hint}`);
+    severity === 'warn' ? warn++ : fail++;
+  }
+}
+
+async function ping(url, label) {
+  return new Promise(resolve => {
+    https.get(url, { timeout: 5000 }, res => {
+      check(`${label} reachable (HTTP ${res.statusCode})`, res.statusCode < 500);
+      resolve();
+    }).on('error', err => {
+      check(`${label} reachable`, false, err.message);
+      resolve();
+    });
+  });
+}
+
+(async () => {
+  console.log('\n⚡ Crypto Swap Agent — Setup Check\n');
+
+  // Env vars
+  console.log('─── Environment Variables ───────────────────────');
+  check('FEE_RECIPIENT_ADDRESS set',
+    !!process.env.FEE_RECIPIENT_ADDRESS && !process.env.FEE_RECIPIENT_ADDRESS.includes('your_address'),
+    'Set a valid thor1... address to receive 0.5% affiliate fees');
+  check('SWAP_FEE_BPS set',
+    !!process.env.SWAP_FEE_BPS,
+    'Default: 50 (= 0.5%). Add to .env', 'warn');
+  check('WALLET_PRIVATE_KEY set (for autonomous execution)',
+    !!process.env.WALLET_PRIVATE_KEY,
+    'Optional for quote-only mode. Required for autonomous swap execution.', 'warn');
+  check('EVM_RPC_URL set',
+    !!process.env.EVM_RPC_URL && !process.env.EVM_RPC_URL.includes('your_key'),
+    'Required for EVM swap execution. Get free key at alchemy.com', 'warn');
+  check('PORT set', !!process.env.PORT, 'Default: 3000', 'warn');
+
+  // Connectivity
+  console.log('\n─── Connectivity ─────────────────────────────────');
+  await ping('https://thornode.ninerealms.com/thorchain/inbound_addresses', 'THORChain NineRealms');
+  await ping('https://midgard.ninerealms.com/v2/pools?limit=1', 'THORChain Midgard');
+  await ping('https://api.coingecko.com/api/v3/ping', 'CoinGecko');
+
+  // Summary
+  console.log('\n─── Summary ──────────────────────────────────────');
+  console.log(`  ${GREEN}${pass} passed${RESET}  ${YELLOW}${warn} warnings${RESET}  ${RED}${fail} failed${RESET}`);
+  if (fail > 0) {
+    console.log(`\n${RED}⚠ Fix failed checks before deploying.${RESET}`);
+    process.exit(1);
+  } else if (warn > 0) {
+    console.log(`\n${YELLOW}⚠ Warnings present — check before going live.${RESET}`);
+    console.log('\nReady for: node src/test.js → then deploy to Railway');
+  } else {
+    console.log(`\n${GREEN}✓ All checks passed. Deploy with: railway up${RESET}`);
+  }
+})();

package/src/formatter.js

@@ -0,0 +1,56 @@
+/**
+ * Output formatters — structured JSON responses for OpenClaw + agent consumers
+ */
+
+export function formatQuote(quoteData, parsed) {
+  const routes = quoteData.routes || [];
+  if (!routes.length) {
+    return { success: false, error: 'No routes found', pair: `${parsed.fromAsset} → ${parsed.toAsset}` };
+  }
+
+  const best = routes[0];
+  return {
+    success: true,
+    pair: `${parsed.fromAsset} → ${parsed.toAsset}`,
+    sellAmount: parsed.amount,
+    expectedOutput: best.expectedOutputMaxSlippage,
+    expectedOutputOptimal: best.expectedOutput,
+    priceImpact: best.priceImpactPercent,
+    route: best.providers?.join(' → ') || 'THORChain',
+    estimatedTimeSeconds: best.estimatedTime,
+    affiliateFee: '0.5%',
+    warning: best.warnings?.[0] || null,
+    rawRoutes: routes.length,
+    timestamp: new Date().toISOString()
+  };
+}
+
+export function formatSwapResult(swapData) {
+  return {
+    success: true,
+    status: swapData.status,
+    memo: swapData.memo,
+    depositAddress: swapData.depositAddress,
+    depositAsset: swapData.depositAsset,
+    depositAmount: swapData.depositAmount,
+    expectedOutput: swapData.expectedOutput,
+    route: swapData.route,
+    affiliateFee: swapData.affiliateFee,
+    nextStep: swapData.warning,
+    timestamp: new Date().toISOString()
+  };
+}
+
+export function formatAssetList(assets) {
+  return {
+    success: true,
+    count: assets.length,
+    assets: assets.slice(0, 50).map(a => ({
+      identifier: a.identifier || a.asset,
+      chain: a.chain,
+      symbol: a.ticker || a.symbol,
+      decimals: a.decimals
+    })),
+    note: 'Showing top 50. Full list available via SwapKit API.'
+  };
+}

package/src/health.js

@@ -0,0 +1,27 @@
+/**
+ * health.js — Health check Express router
+ * Provides GET /health endpoint for Railway.app and uptime monitors.
+ */
+
+import { Router } from 'express';
+
+const router = Router();
+
+const VERSION = process.env.npm_package_version || '1.0.0';
+
+/**
+ * GET /health
+ * Returns service health status, version, and current timestamp.
+ * Used by Railway.app health checks and external uptime monitors.
+ *
+ * Response: { status: 'ok', version: '1.0.0', timestamp: '<ISO8601>' }
+ */
+router.get('/health', (req, res) => {
+  res.status(200).json({
+    status: 'ok',
+    version: VERSION,
+    timestamp: new Date().toISOString(),
+  });
+});
+
+export default router;

package/src/index.js

@@ -0,0 +1,72 @@
+/**
+ * Crypto Swap Agent — MoreBetter Studios
+ * Cross-chain swap skill via THORChain direct integration
+ *
+ * Entry point:
+ *   node src/index.js              → starts HTTP server
+ *   node src/index.js quote ...    → CLI mode (local testing)
+ */
+
+import 'dotenv/config';
+import { SwapKitApi } from './swapkit.js';
+import { parseSwapCommand } from './parser.js';
+import { formatQuote, formatSwapResult, formatAssetList } from './formatter.js';
+
+const FEE_BPS = parseInt(process.env.SWAP_FEE_BPS || '50');
+const FEE_ADDRESS = process.env.FEE_RECIPIENT_ADDRESS || '';
+
+const CLI_COMMANDS = ['quote', 'execute', 'status', 'assets', 'list'];
+const firstArg = process.argv[2]?.toLowerCase();
+
+if (firstArg && CLI_COMMANDS.includes(firstArg)) {
+  // ── CLI mode ──────────────────────────────────────────────────────────────
+  const api = new SwapKitApi({ feeBps: FEE_BPS, feeAddress: FEE_ADDRESS });
+  const command = process.argv.slice(2).join(' ');
+
+  async function main(command) {
+    const parsed = parseSwapCommand(command);
+
+    switch (parsed.action) {
+      case 'quote': {
+        const quote = await api.getQuote(parsed.fromAsset, parsed.toAsset, parsed.amount);
+        console.log(JSON.stringify(formatQuote(quote, parsed), null, 2));
+        break;
+      }
+      case 'execute': {
+        if (!parsed.destAddress) {
+          console.log(JSON.stringify({ error: 'Destination address required for execute' }));
+          process.exit(1);
+        }
+        const result = await api.executeSwap(parsed.fromAsset, parsed.toAsset, parsed.amount, parsed.destAddress);
+        console.log(JSON.stringify(formatSwapResult(result), null, 2));
+        break;
+      }
+      case 'status': {
+        const status = await api.getStatus(parsed.txHash);
+        console.log(JSON.stringify(status, null, 2));
+        break;
+      }
+      case 'assets': {
+        const assets = await api.getSupportedAssets();
+        console.log(JSON.stringify(formatAssetList(assets), null, 2));
+        break;
+      }
+      default:
+        console.log(JSON.stringify({
+          error: `Unknown command: ${parsed.action}`,
+          supported: ['quote', 'execute', 'status', 'assets'],
+        }));
+        process.exit(1);
+    }
+  }
+
+  main(command).catch(err => {
+    console.log(JSON.stringify({ error: err.message }));
+    process.exit(1);
+  });
+
+} else {
+  // ── Server mode ───────────────────────────────────────────────────────────
+  const { startServer } = await import('./server.js');
+  startServer();
+}

package/src/mcp.js

@@ -0,0 +1,200 @@
+/**
+ * mcp.js — Model Context Protocol server for FORGE
+ * Exposes 4 tools via Streamable HTTP transport (2026 spec).
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Router } from 'express';
+
+const TOOLS = [
+  {
+    name: 'forge_quote',
+    description:
+      'Get a cross-chain swap quote via THORChain. Returns expected output, fees, route, and slippage. Use before executing any swap.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromAsset: {
+          type: 'string',
+          description: 'Source asset in CHAIN.TICKER format e.g. ETH.ETH, BTC.BTC, AVAX.USDC',
+        },
+        toAsset: {
+          type: 'string',
+          description: 'Destination asset in CHAIN.TICKER format',
+        },
+        amount: {
+          type: 'string',
+          description: 'Amount to swap in human-readable units e.g. 0.1',
+        },
+      },
+      required: ['fromAsset', 'toAsset', 'amount'],
+    },
+  },
+  {
+    name: 'forge_execute',
+    description:
+      'Build a cross-chain swap transaction. Returns the vault deposit address and memo — the user\'s wallet sends funds to this address with the memo to execute the swap. FORGE never holds funds.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromAsset: { type: 'string' },
+        toAsset: { type: 'string' },
+        amount: { type: 'string' },
+        destinationAddress: {
+          type: 'string',
+          description: 'Recipient address for the destination asset',
+        },
+      },
+      required: ['fromAsset', 'toAsset', 'amount', 'destinationAddress'],
+    },
+  },
+  {
+    name: 'forge_assets',
+    description:
+      'List all supported assets available for cross-chain swapping via FORGE/THORChain.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'forge_status',
+    description: 'Check the status of a cross-chain swap by transaction hash.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        txHash: {
+          type: 'string',
+          description: 'Transaction hash to check',
+        },
+      },
+      required: ['txHash'],
+    },
+  },
+];
+
+/**
+ * Create an Express Router that mounts an MCP server at /mcp.
+ * @param {import('./swapkit.js').SwapKitApi} swapApi
+ * @returns {import('express').Router}
+ */
+export function createMcpRouter(swapApi) {
+  const router = Router();
+
+  // Build MCP server once; transports are per-request (stateless mode)
+  const server = new Server(
+    { name: 'forge', version: '0.1.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  // List tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  // Call tool
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result;
+
+      switch (name) {
+        case 'forge_quote': {
+          const { fromAsset, toAsset, amount } = args;
+          result = await swapApi.getQuote(fromAsset, toAsset, parseFloat(amount));
+          break;
+        }
+        case 'forge_execute': {
+          const { fromAsset, toAsset, amount, destinationAddress } = args;
+          result = await swapApi.executeSwap(
+            fromAsset,
+            toAsset,
+            parseFloat(amount),
+            destinationAddress
+          );
+          break;
+        }
+        case 'forge_assets': {
+          result = await swapApi.getSupportedAssets();
+          break;
+        }
+        case 'forge_status': {
+          const { txHash } = args;
+          result = await swapApi.getStatus(txHash);
+          break;
+        }
+        default:
+          return {
+            content: [{ type: 'text', text: `Error: Unknown tool: ${name}` }],
+            isError: true,
+          };
+      }
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // POST /mcp — fresh server + transport per request (stateless)
+  router.post('/', async (req, res) => {
+    try {
+      // Create a fresh server instance for each request — MCP transport is stateful
+      const reqServer = new Server(
+        { name: 'forge', version: '0.1.0' },
+        { capabilities: { tools: {} } }
+      );
+
+      // Register tools on the fresh instance
+      reqServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+      reqServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+          let result;
+          switch (name) {
+            case 'forge_quote': {
+              const { fromAsset, toAsset, amount } = args;
+              result = await swapApi.getQuote(fromAsset, toAsset, parseFloat(amount));
+              break;
+            }
+            case 'forge_execute': {
+              const { fromAsset, toAsset, amount, destinationAddress } = args;
+              result = await swapApi.executeSwap(fromAsset, toAsset, parseFloat(amount), destinationAddress);
+              break;
+            }
+            case 'forge_assets': {
+              result = await swapApi.getSupportedAssets();
+              break;
+            }
+            case 'forge_status': {
+              const { txHash } = args;
+              result = await swapApi.getStatus(txHash);
+              break;
+            }
+            default:
+              return { content: [{ type: 'text', text: `Error: Unknown tool: ${name}` }], isError: true };
+          }
+          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        } catch (err) {
+          return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+        }
+      });
+
+      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+      await reqServer.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      if (!res.headersSent) res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}