# Smeltor — The intelligence layer for DeFi > Smeltor is a non-custodial DeFi routing API. You describe what the > user wants in natural language or as a structured intent; we return > 1–3 ranked routes with ready-to-sign transaction calldata. The user's > wallet executes — Smeltor never holds funds. This file is optimized for LLM / AI-agent consumption. Human-readable docs live at https://basiyx.vercel.app/docs and the OpenAPI spec is at https://basiyx.vercel.app/openapi.yaml. --- ## Quick facts - Base URL (production): `https://basiyx.vercel.app` - Base URL (after smeltor.com migration): `https://smeltor.com` - Auth: open access (Phase 1). Rate-limited per IP. API keys arriving in Phase 2. - Chains: Base (8453), Arbitrum (42161), Ethereum (1). Solana via Jupiter for swap. - Categories supported: swap, bridge, earn (lending + vaults), staking, restaking, perpetuals, LP, fixed yield, synthetic yield, institutional credit. - Protocols: 23 (Aave, Moonwell, Compound, Spark, Morpho, Lido, Rocket Pool, ether.fi, Pendle, Ethena, Maple, Hyperliquid, GMX, Aerodrome, Across, Stargate, …). - Aggregators: 7 (1inch, ParaSwap, KyberSwap, OpenOcean, Odos, 0x, Jupiter). - MCP server: `@smeltor/mcp` on npm — same endpoints exposed as MCP tools. --- ## The single endpoint to know ``` POST /api/public/workflow/resolve ``` Three input shapes, all return the same `routes[]` envelope. ### 1. Natural language ```json { "walletAddress": "0xabc…", "intent": "earn 5% on 100 USDC" } ``` ### 2. Structured action (skip the parser) ```json { "walletAddress": "0xabc…", "action": "earn", "params": { "token": "USDC", "amount": "100", "chain": "base" } } ``` ### 3. Pre-composed steps (skip the resolver entirely) ```json { "walletAddress": "0xabc…", "steps": [ { "action": "swap", "params": { "fromToken": "ETH", "toToken": "USDC", "amount": "0.1", "chain": "base" } }, { "action": "earn", "params": { "token": "USDC", "amount": "200", "chain": "base" } } ] } ``` --- ## Response shape ```json { "intent": "Earn 5.05% APY via Moonwell on Base", "walletSummary": "Holds 250 USDC on arbitrum, 0.1 ETH on base.", "routes": [ { "id": "route_a4f9b1c2", "label": "highest_yield", "summary": "Earn 5.05% APY via Moonwell on Base", "steps": [ /* ComposedStep[] with transactions[] */ ], "signatureCount": 1, "executionMode": "multicall", "metrics": { "estimatedYield": "5.05%", "bridgeRequired": true, "estimatedGas": "$0.04", "estimatedTime": "30s", "chains": ["arbitrum", "base"] }, "tradeoffs": "Higher yield. Requires bridging funds to Base.", "warnings": [], "reasoning": ["Moonwell on Base offers 5.05% APY; Aave on Arbitrum offers 3.27%."] }, { "id": "route_e7c3d8a1", "label": "same_chain", "summary": "Earn 3.27% APY via Aave on Arbitrum", "metrics": { "estimatedYield": "3.27%", "bridgeRequired": false, "chains": ["arbitrum"] }, "tradeoffs": "Lower yield. No bridging required." } ], "routeCount": 2, "signatureCount": 1, "executionMode": "multicall", "warnings": [] } ``` --- ## Multi-route, never recommended The resolver returns 1–3 ranked routes. Labels are TECHNICAL descriptors: - `highest_yield` — highest APY available, may require a bridge - `same_chain` — alternative that avoids bridging - `fixed_rate` — Pendle / fixed-rate venue - `lowest_cost` — minimizes total gas/fees - `no_bridge` — explicitly bridge-free - `primary` — fallback label when none of the above apply The agent picks. The user picks. We never use "best", "recommended", or "for you". This is a legal positioning, not a stylistic choice. --- ## All actions | Action | Purpose | | --------------- | -------------------------------------------- | | `swap` | Token swap via 7-aggregator race | | `bridge` | Cross-chain via Across or Stargate | | `earn` | Supply to lending / staking / restaking / vault / synthetic yield | | `earn_withdraw` | Pull funds out of an earn position | | `perp_open` | Open Hyperliquid or GMX perp | | `perp_close` | Close a perp | | `perp_deposit` | Move USDC into HL margin | | `perp_withdraw` | HL → Arbitrum | | `exit_all` | Close every position back to USDC | | `yield_hop` | Move from one yield venue to a higher one | | `take_profit` | Close perp at target, route into yield | | `rebalance` | Adjust allocations across positions | | `twap` / `dca` | Time-weighted swap via CoW Protocol | | `lp_add` | Aerodrome v2 LP | | `lp_remove` | Withdraw from Aerodrome v2 LP | --- ## Single-action endpoints (when the agent already knows what it wants) | Endpoint | Method | Purpose | | ----------------------------------------- | ------ | ------------------------------------ | | `/api/public/swap/best-quote` | POST | Race 7 aggregators for a swap | | `/api/public/swap/status` | GET | Tx status by hash + chain | | `/api/public/swap/tokens` | GET | Supported token registry | | `/api/public/earn/best-deposit` | POST | Race 5 protocols for an earn deposit | | `/api/public/earn/withdraw` | POST | Withdraw from a specific protocol | | `/api/public/earn/positions` | GET | Read user's active earn positions | | `/api/public/earn/lp-add` | POST | Aerodrome LP add | | `/api/public/earn/lp-remove` | POST | Aerodrome LP remove | | `/api/public/bridge/quote` | POST | Across or Stargate quote + tx | | `/api/public/bridge/status` | GET | Track a bridge by deposit ID | | `/api/public/perp/order` | POST | Build HL or GMX perp tx | | `/api/public/perp/withdraw` | POST | HL withdraw3 calldata | | `/api/public/workflow/twap/plan` | POST | TWAP order plan | | `/api/public/workflow/twap/status` | GET | TWAP order status | | `/api/public/system/coverage` | GET | Live capability matrix | All single-action POSTs return the same `transactions[]` shape that `/resolve` embeds inside steps. Response includes any aggregator failures so the agent can decide whether to retry. --- ## Pre-built workflow shortcuts Each is a thin wrapper over `/resolve` with a hardcoded `steps[]`: - `POST /api/public/workflow/swap-and-earn` — token → USDC → vault - `POST /api/public/workflow/bridge-and-trade` — bridge → swap on destination - `POST /api/public/workflow/deposit-and-trade` — fund HL → open perp - `POST /api/public/workflow/yield-hop` — exit one earn, enter another - `POST /api/public/workflow/take-profit-to-yield` — close perp → earn - `POST /api/public/workflow/close-and-redeploy` — close perp → swap - `POST /api/public/workflow/idle-to-yield` — sweep stables → earn - `POST /api/public/workflow/rebalance` — multi-position rebalance - `POST /api/public/workflow/emergency-exit` — close everything to USDC - `POST /api/public/workflow/twap` — time-weighted swap - `POST /api/public/workflow/dca` — alias for twap --- ## Example: end-to-end agent flow ```bash # 1. Resolve intent curl -sS https://basiyx.vercel.app/api/public/workflow/resolve \ -X POST -H 'Content-Type: application/json' \ -d '{"walletAddress":"0xabc…","intent":"earn yield on 5 USDC"}' # 2. Inspect routes[], pick by label / metrics # 3. For each step in the chosen route: # - If step.transactions[] exists, sign each tx with the user's wallet # - If step.typedData exists (HL orders), sign as EIP-712 typed data # 4. Broadcast and await receipt ``` A full reference implementation lives in `scripts/agent-test.ts` in the Smeltor repo. --- ## Rate limits Per-IP, per-minute, applied at the route level: | Endpoint pattern | Limit | | ------------------------------------------ | ------- | | `/swap/best-quote` | 10/min | | `/earn/best-deposit` | 10/min | | `/bridge/quote` | 10/min | | `/workflow/resolve` | 5/min | | `/perp/order` | 10/min | | Aggregator proxies (`/aggregators/*/quote`)| 60/min | | `/system/coverage` | 60/min | 429 responses include `Retry-After` (seconds). --- ## Error shapes ```json { "error": "Token 'XYZ' not found on base" } ``` | Status | Meaning | | ------ | ---------------------------------------------------------- | | 400 | Bad input (invalid token, malformed amount, missing field) | | 429 | Rate-limited (read `Retry-After`) | | 502 | All upstream aggregators / composer steps failed | | 500 | Server-side issue (`details` included in non-prod) | We don't return 404 for "no quote" — that's a 502 with `failedAggregators`, because the route exists but no upstream cooperated. --- ## MCP server ```json { "mcpServers": { "smeltor": { "command": "npx", "args": ["@smeltor/mcp"], "env": { "SMELTOR_API_BASE": "https://basiyx.vercel.app" } } } } ``` Tool names mirror endpoint paths: `resolve_workflow`, `swap_best_quote`, `earn_best_deposit`, `bridge_quote`, `perp_order`, `system_coverage`. --- ## What Smeltor is NOT - Not a wallet — we never store or sign with private keys - Not a custodian — funds never touch Smeltor balances - Not a financial advisor — we present options, agents/users pick - Not a smart contract platform — we deploy zero contracts on-chain - Not a bridge — we route through Across, Stargate, and aggregators Smeltor is read-and-route infrastructure. The chain executes. --- ## Contact Email: ben@smeltor.com (or bentheboring1@gmail.com) GitHub: github.com/smeltor (private alpha — request access via email) Demo: https://basiyx.vercel.app/demo Docs: https://basiyx.vercel.app/docs OpenAPI: https://basiyx.vercel.app/openapi.yaml