Ophis Swap

Swap workflow

1. Understand the request. If it is plain English ("swap 100 USDC for ETH on Base"), call parse_intent to extract sell token, buy token, amount, and chain. Note that parse_intent returns token symbols, not addresses.
2. Confirm the chain. Call list_chains and use a chainId from tradeable. If the chain is in paused, tell the user it is not live yet.
3. Resolve token addresses (hard rule 1). For each token symbol, call resolve_token(chainId, symbol). Use canonical.address and canonical.decimals when found is true and ambiguous is false; confirm an ambiguous result with the user; for a found: false symbol, fall back to the on-chain readback plus user confirmation. Apply hard rule 4 for native coins.
4. Show the edge (recommended). Call expected_surplus for beatBps, the difference versus a public reference aggregator. It is advisory, not a guarantee; a positive value means Ophis quoted more output than that single reference.
5. Quote. Call get_quote with kind ("sell" or "buy"), the amount in atoms, the two addresses, and the trader address from.
6. Build the order. Call build_order with the owner, the tokens, kind, the slippage-adjusted sellAmount and buyAmount (scaled with each token's true decimals, hard rule 2), an explicit slippageBips (hard rule 3), and, if you are an Ophis integrator, your referrerCode. The result includes order, signing (EIP-712 domain, types, primaryType), fullAppData, appDataHash, and partnerFee.
7. Sanity-check the bound. Format order.buyAmount (your minimum received) with the buy token's true decimals and confirm it is in the ballpark the user expects. If it looks far too low, stop and recheck decimals and the buy token address.
8. Confirm, then sign (hard rule 5). Show the user the full picture, including the buy token ADDRESS. On explicit approval, sign the signing payload with the owner wallet. If not approved, stop.
9. Submit. Call submit_order with the exact order object, the signature, from (the owner), and the exact fullAppData string from step 6. It returns the order UID.
10. Report. Give the user the order UID. The order is now a live commitment that a solver can fill at the signed limit any time until validTo. The MCP has no cancel tool; an open order can still be cancelled gasless with a signed EIP-712 cancellation, see the ophis-cancel skill at https://ophis.fi/.well-known/agent-skills/ophis/skills/ophis-cancel.md. Otherwise it stands until it fills or expires.

Worked example

A market-style sell, "swap 100 USDC for WETH on Base". The argument names and response shapes below follow reference.md; the addresses are placeholders, so always take the real ones from resolve_token.

parse_intent(text="swap 100 USDC for WETH on Base")
  -> { intent: "swap", entities: [
        { type: "amount", value: "100" }, { type: "sellToken", value: "USDC" },
        { type: "buyToken", value: "WETH" }, { type: "chain", value: "Base" } ] }
# Read the entity values, then map the symbols and chain name to ids yourself.

list_chains()                                # confirm Base, chainId 8453, is `tradeable`
resolve_token(chainId=8453, symbol="USDC")   # -> canonical.address = <USDC>, decimals = 6
resolve_token(chainId=8453, symbol="WETH")   # -> canonical.address = <WETH>, decimals = 18

# Amounts are atoms = whole units x 10^decimals:  100 USDC (6 dp) -> "100000000"

get_quote(chainId=8453, sellToken=<USDC>, buyToken=<WETH>, kind="sell",
          amount="100000000", from="<your wallet>")
  -> { quote: { sellAmount, buyAmount, feeAmount, validTo } }

# Minimum received = quote.buyAmount adjusted down for slippage (here 75 bps).
build_order(chainId=8453, owner="<your wallet>", sellToken=<USDC>, buyToken=<WETH>,
            kind="sell", sellAmount="100000000", buyAmount="<min from quote>",
            slippageBips=75)
  -> { order, signing: { domain, types, primaryType: "Order" }, fullAppData, appDataHash, partnerFee }

# Confirm with the user before signing (hard rule 5): the buy token ADDRESS, the
# minimum received (order.buyAmount at WETH's 18 decimals), the slippage, the fee (partnerFee; order.feeAmount is 0),
# and the validity window. Only on explicit approval, sign the `order` object as
# EIP-712 typed data using `signing` (domain + types + primaryType); the receiver
# is pinned to owner. If the user does not approve, stop.

submit_order(chainId=8453, order=order, signature="0x...", from="<your wallet>",
             fullAppData=fullAppData)
  -> orderUID

Reading data (no signing, safe to call freely)

• get_balances and get_portfolio: native and ERC-20 balances on one chain or across chains. Use these for the token readback in hard rule 1.
• get_gas: current gas price. Ophis trades are gasless for the trader, so this is informational.
• get_token_chart: OHLCV price history. It is backed by a shared keyless quota, so cache results and do not poll tightly.
• lookup_tier: a wallet's fee-rebate tier and rebate percentage.
• expected_surplus: the beat-the-market comparison described above.

Fees and rebates

Ophis applies a small volume fee, shown as partnerFee (currently 5 bps), and shares a rebate back through its referrer program. The order's feeAmount is always 0; the volume fee is the only charge. The rebate is tiered by 30-day USD volume: it starts at the bronze tier (about 20,000 USD of 30-day volume, 10 percent) and rises through silver, gold, palladium, and platinum (1,000,000 USD, 50 percent); below the bronze threshold a wallet earns 0 percent. Pass a referrerCode in build_order to attribute volume to your code, and check a wallet's current tier and rate with lookup_tier.

Supported chains

Trading is live on Ethereum (1), Optimism (10), BNB Chain (56), Gnosis (100), Unichain (130), Polygon (137), Base (8453), Arbitrum (42161), Avalanche (43114), Plasma (9745), Ink (57073), and Linea (59144). Some chains have settlement deployed but no live orderbook yet. Always treat list_chains as the authoritative live set, since it splits tradeable from paused at runtime. The read tools (get_balances, get_portfolio, get_gas, get_token_chart) cover the subset of chains that have a keyless public RPC.

Order lifetime

Orders are signed with a validity window (validForSeconds, default 1200 seconds, that is 20 minutes; minimum 60). A submitted order is a live, fillable commitment at the signed limit price for that whole window, so keep the window short for a market-style intent. Orders default to fill-or-kill (partiallyFillable is false), which is the safer default. The MCP has no cancel tool; to cancel an open order gasless, follow the ophis-cancel skill from the Ophis skill family (https://ophis.fi/.well-known/agent-skills/ophis/). A submitted order that is not cancelled stands until it fills or expires.

When the MCP server is unavailable

Intent parsing and the beat-the-market comparison are also reachable over plain HTTP at https://swap.ophis.fi/api/intent and https://swap.ophis.fi/api/beat-market (no key, allow-listed origins). The full build-and-submit flow is available only through the MCP tools.

See reference.md for the exact input and output schema of every tool.