Smeltor — Developer Documentation

Version 3.0 · 31 May 2026

What is Smeltor?

Smeltor is the composition layer for on-chain finance. One integration gives your app, agent, or wallet access to swaps, yield, leverage, borrowing, and cross-chain transfers across 41 protocols and 10 chains — without integrating each protocol separately.

You send a structured action (or a natural-language intent). Smeltor resolves it into a multi-step plan, compares the available options across protocols and chains, and returns ready-to-sign calldata. Smeltor presents the options; your agent or user chooses; the user's own wallet executes directly with the protocol. We never hold, control, or touch funds.

Works with AI agents (MCP), wallet apps and trading bots (REST API), or any product that needs DeFi.

The model, stated precisely:

• We present ranked options and compute the route.
• Your agent or user chooses which option to take.
• The user's wallet signs and executes the transaction directly with the protocol.

We are not a custodian, a router contract, or an execution venue. There is no Smeltor contract in the transaction path.

Quickstart — your first swap

No SDK required. No API key required for the developer preview. Just HTTP.

Step 1 — get a swap quote

curl https://api.smeltor.com/api/public/swap/best-quote \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "fromToken": "USDC",
    "toToken": "ETH",
    "amount": "100",
    "chain": "base",
    "walletAddress": "YOUR_WALLET_ADDRESS"
  }'

Response (shape):

{
  "bestAggregator": "paraswap",
  "estimatedOutput": "0.0289...",
  "transactions": [
    {
      "to": "0x6A000F20005980200259B80c5102003040001068",
      "data": "0x...",
      "value": "0",
      "chainId": 8453
    }
  ],
  "approvalSpender": "0x6A000F20005980200259B80c5102003040001068",
  "allQuotes": [ /* every aggregator that returned a quote, ranked */ ]
}

The to address is the aggregator's own router — never a Smeltor contract.

Step 2 — send the transaction from your app

// ethers.js, viem, web3.js, or any library
const tx = quote.transactions[0];
const hash = await wallet.sendTransaction({
  to: tx.to,
  data: tx.data,
  value: tx.value,
});

That's it. The swap raced up to 6 aggregators for the best rate and executed directly against the winning aggregator's router. Smeltor was never in the money path.

Quickstart — AI agent (MCP)

Connect any MCP-compatible agent (Claude Desktop, AgentKit, custom runtimes) to the Smeltor MCP server.

Config:

{
  "mcpServers": {
    "smeltor": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.smeltor.com/mcp"]
    }
  }
}

Available tools (all live):

How an agent uses it: your agent interprets what the user wants and calls the relevant tool with a structured action. Smeltor returns ranked options and signable calldata. The agent presents the options to the user (or signs with a hot wallet under its own policy). The agent decides; Smeltor resolves and returns the route.

Note on parse_intent: Smeltor does not interpret natural language as its core function — your LLM already does that better. parse_intent exists only as a convenience fallback when you want to see how a freeform string maps to a structured action. In normal use, call smeltor_swap / smeltor_earn / smeltor_perp / smeltor_workflow directly with structured parameters.

Composition — the core capability

Most DeFi APIs optimize one action. Smeltor composes across actions and chains.

POST /api/public/workflow/resolve takes either a structured action + params, or a natural-language intent, and returns a multi-step plan with ready-to-sign calldata. If the funds are on the wrong chain, it inserts a bridge step. If a step depends on a previous step's output, it pipes the amount forward. Each step returns ready-to-sign calldata.

curl https://api.smeltor.com/api/public/workflow/resolve \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x...",
    "intent": "earn yield on USDC on arbitrum"
  }'

Response (shape):

{
  "intent": "earn yield on USDC on Arbitrum",
  "walletSummary": "USDC on Base, ETH on Ethereum",
  "signatureCount": 1,
  "executionMode": "multicall",
  "rankedBy": "net APY after bridge cost",
  "disclaimer": "These are ranked options, not recommendations. You choose which to execute.",
  "reasoning": [
    "USDC is on Base; target chain is Arbitrum — adding a bridge step",
    "Compared yield options on Arbitrum, ranked by net APY",
    "Collapsed bridge + deposit into a single signature via Across MulticallHandler"
  ],
  "steps": [ /* each step with real, ready-to-sign calldata */ ]
}

The plan is a set of options and a route — your agent or user picks and signs. The resolver computes what's needed (including steps the caller didn't know they needed); it does not decide on the user's behalf.

Capabilities

What your users can do, the moment you integrate:

All endpoints

Full OpenAPI spec: https://api.smeltor.com/openapi.yaml
Live coverage report: GET /api/public/system/coverage

Swap (3):

POST /api/public/swap/best-quote     — race up to 6 aggregators, return ranked
GET  /api/public/swap/status         — check swap transaction status
GET  /api/public/swap/tokens         — list tradeable tokens per chain

Earn (6):

POST /api/public/earn/best-deposit   — compare 20+ yield protocols, return ranked
POST /api/public/earn/withdraw       — exit a yield position
GET  /api/public/earn/positions      — read current deposits + accrued yield
POST /api/public/earn/claim          — claim reward tokens
POST /api/public/earn/lp-add         — add liquidity (Aerodrome)
POST /api/public/earn/lp-remove      — remove liquidity (Aerodrome)

Bridge (2):

POST /api/public/bridge/quote        — race Across vs Stargate, return better output
GET  /api/public/bridge/status       — track bridge completion

Perps (1):

POST /api/public/perps/order         — open or close a leveraged position

Workflows (composition):

POST /api/public/workflow/resolve            — intent or structured action → composed plan
POST /api/public/workflow/swap-and-earn      — swap + deposit for yield
POST /api/public/workflow/bridge-and-trade   — bridge + open perp position
POST /api/public/workflow/deposit-and-trade  — deposit to perp venue + open position
POST /api/public/workflow/close-and-redeploy — close perp + redeploy capital
POST /api/public/workflow/rebalance          — rebalance to a target allocation
POST /api/public/workflow/yield-hop          — move deposit to a higher-yielding protocol
POST /api/public/workflow/take-profit-to-yield — close a winning position, earn on profits
POST /api/public/workflow/emergency-exit     — close everything, consolidate to stablecoin
POST /api/public/workflow/idle-to-yield      — surface idle funds, present yield options
POST /api/public/workflow/twap/plan          — TWAP/DCA via CoW Protocol
GET  /api/public/workflow/twap/status        — track TWAP execution
POST /api/public/workflow/dca/plan           — DCA plan
GET  /api/public/workflow/dca/status         — track DCA execution

System (1):

GET  /api/public/system/coverage     — live report of all protocols, chains, capabilities

Coverage

41 protocols across 10 chains. (Live counts always available at GET /api/public/system/coverage.)

Chains and what runs where:

Swap aggregators raced (up to 6): 1inch, ParaSwap, KyberSwap, OpenOcean, 0x, Odos. Plus on-chain DEX venues (Balancer V2, TraderJoe, SyncSwap) where applicable. Solana routes via Jupiter v6.

Earn (multiple protocols): Aave, Moonwell, Morpho, Compound V3, Fluid, Spark, Maple, Beefy (variable) · Pendle (fixed yield) · Lido, Rocket Pool, ether.fi, Marinade (staking/LST/LRT) · Ethena · plus chain-specific (Benqi, Venus, Convex, Yearn V3, Fraxlend, Kamino).

Bridge: Across, Stargate V2 (Ondo Bridge for tokenized assets to HyperEVM).

Perps: Hyperliquid.

Status note: some protocols are surfaced for discovery but marked coming_soon (not yet routable via /resolve) or paused (temporarily disabled — e.g. Drift, frozen after its April 2026 exploit). The live /system/coverage and get_tokens responses are the source of truth for what's executable right now. Always trust the live coverage response over any static list, including this one.

Testnet

Test with real calldata on testnet — no real funds, no risk.

Pass "testnet": true on smeltor_swap, smeltor_earn, smeltor_perp, or a structured smeltor_workflow action. Natural-language intent is mainnet-only on testnet calls (returns TESTNET_NL_NOT_SUPPORTED) — use structured action + params for testnet composition.

curl https://api.smeltor.com/api/public/workflow/resolve \
  -X POST -H "Content-Type: application/json" \
  -d '{"action":"earn","params":{"token":"USDC","amount":"10","chain":"base"},"testnet":true,"walletAddress":"0x..."}'

Returns real Base Sepolia calldata (chainId: 84532, real Aave V3 Pool address, mock: false). Note: testnet plans return calldata but are not pre-checked against live chain state the way mainnet plans are.

Partner fees

Earn revenue on every transaction your users make through Smeltor.

Add to any action endpoint or /workflow/resolve:

{
  "integratorFee": {
    "bps": 25,
    "recipient": "0xYOUR_WALLET"
  }
}

• bps — your fee in basis points (1–500; 25 = 0.25%). Integer basis points only, not a percentage value.
• recipient — your fee-collection address.

How it's collected: the fee is a separate ERC-20 transfer prepended to the transaction list — collected in the same signing flow as the user's action, not batched or claimed later. It is deducted from the input. Smeltor's own base fee is separate and unaffected. The 500 bps (5%) cap prevents abuse.

Note: API keys (coming for production partners) attach fee attribution and analytics to your calls. In the open preview, pass integratorFee directly.

Security model

Zero smart contracts. No funds held, ever.

Smeltor has deployed no code to any blockchain. Funds flow directly from the user's wallet to the protocol. Smeltor's role is to compute the route, build the calldata, and return it.

What this means:

• Nothing to exploit — there is no Smeltor contract in the path (unlike router-contract bridges that have been exploited for millions).
• No rug risk — Smeltor never has access to funds.
• Every transaction is user-signed — nothing executes without explicit wallet approval.
• Every transaction is on-chain auditable — identical to the user going to the protocol directly.

Approval-spender whitelist: every approval Smeltor returns targets an audited protocol/aggregator router on a maintained per-chain allowlist. Calldata that would approve an unrecognised spender is rejected.

Protocol kill switch: if an integrated protocol is compromised, it can be disabled across all endpoints and the resolver in seconds, with no code deploy. The resolver routes around disabled protocols automatically.

Audit status: Smeltor is in developer preview. The non-custodial, zero-contract architecture means the blast radius of any issue is limited to plan generation (a user signing a plan), not custody. A formal third-party security review of the calldata-generation layer is planned before production partner onboarding. Treat the preview accordingly: test thoroughly, start small.

Single-signature cross-chain

Cross-chain flows usually need several signatures (bridge, approve, deposit). Where a flow bridges via Across, Smeltor uses the Across MulticallHandler to collapse it into one signature:

• You call /workflow/resolve.
• If the flow crosses chains via Across, the bridge message carries the destination actions.
• The user signs once; Across bridges; MulticallHandler executes the destination actions.
• If anything fails, funds return to the user (fallback recipient).

The response tells you the mode:

{ "signatureCount": 1, "executionMode": "multicall" }

Collapses to 1 signature: bridge (via Across) + on-chain destination action (bridge+earn, bridge+swap, bridge+swap+earn).
Stays multi-signature: same-chain flows, Hyperliquid perps (off-chain signing), Stargate routes, and destination actions on protocols that require a separate approval (e.g. some lending markets). The response always reports the true count — don't assume.

Error handling

All endpoints return consistent error shapes:

{
  "error": "Insufficient USDC balance on Base — need $25, have $0.89",
  "suggestion": "Bridge USDC from Arbitrum or deposit funds",
  "code": "INSUFFICIENT_BALANCE"
}

Common codes: INSUFFICIENT_BALANCE, UNSUPPORTED_TOKEN, UNSUPPORTED_CHAIN, AMOUNT_TOO_LOW, PROTOCOL_PAUSED, QUOTE_EXPIRED, RATE_LIMITED, INVALID_FEE.

Recovery (multi-step): if a step fails mid-execution, call /workflow/resolve again with the same intent. The resolver scans the wallet's current state and builds a fresh plan from where you actually are — it reroutes, it doesn't replay.

Rate limits (developer preview)

The preview is IP-rate-limited. Production partners get API keys with higher limits, usage analytics, and fee attribution. Need higher limits now? Contact us.

FAQ

Do I need an API key?
Not for the preview. Calls are open with IP-based rate limiting, so you can start building immediately — no signup. Production partners get API keys for higher limits, usage analytics, and partner-fee attribution.

Does Smeltor choose the protocol or route for me?
No. Smeltor presents ranked options (by an explicit criterion, with a disclaimer that they're options, not recommendations) and computes the route. Your agent or user chooses which to execute. You can also pin a specific protocol by passing protocol explicitly.

Which chains do you support?
41 protocols across 10 chains. Full multi-action (swap, earn, borrow, bridge) on Base, Arbitrum, Ethereum. Swap + earn + bridge on Polygon, BNB Chain, Avalanche, zkSync. Solana for swaps and yield. Optimism and HyperEVM for cross-chain routing. See /system/coverage for the live picture.

Do you hold user funds?
Never. Transactions go directly from the user's wallet to the protocol. Smeltor builds the calldata; the wallet executes it.

What happens if a protocol gets hacked?
It's disabled instantly via the kill switch, with no code deploy, and the resolver routes around it.

How does the partner fee work?
Add integratorFee: { bps, recipient } to any call. The fee is collected as a separate ERC-20 transfer in the same signing flow — not batched, not claimed later. Basis points only (1–500).

Is Smeltor audited?
Smeltor is in developer preview with a non-custodial, zero-contract architecture. A formal third-party review of the calldata-generation layer is planned before production partner onboarding. Test thoroughly and start small.

Is this financial advice?
No. Smeltor resolves the route for a stated action and presents options ranked by objective criteria (APY, fees, speed). It never recommends what to do — only computes how to execute what you asked for. The user always chooses and signs.

Support

• OpenAPI spec: https://api.smeltor.com/openapi.yaml
• Live coverage: GET /api/public/system/coverage
• Contact: @smeltor on X

Smeltor — the composition layer for on-chain finance. Non-custodial · zero smart contracts · every transaction on-chain.