ophis

<p align="center">
  <img src="apps/frontend/apps/cowswap-frontend/public/ophis-logo-full.svg" alt="Ophis" width="320"/>
</p>

<h1 align="center">Ophis</h1>

<p align="center">
  <b>Describe a trade in plain English. Ophis does the rest.</b><br/>
  An intent-based DEX aggregator with a natural-language layer, built for humans and agents alike.
</p>

<p align="center">
  <a href="https://github.com/ophis-fi/ophis/actions/workflows/ci.yml"><img src="https://github.com/ophis-fi/ophis/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://github.com/ophis-fi/ophis/actions/workflows/codeql.yml"><img src="https://github.com/ophis-fi/ophis/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"/></a>
  <a href="https://github.com/ophis-fi/ophis/actions/workflows/security.yml"><img src="https://github.com/ophis-fi/ophis/actions/workflows/security.yml/badge.svg" alt="Security audits"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue" alt="GPL-3.0 License"/></a>
  <a href="https://ophis.fi"><img src="https://img.shields.io/badge/Optimism-live-7c3aed" alt="OP mainnet live"/></a>
</p>

<p align="center">
  <a href="https://swap.ophis.fi"><b>Swap App</b></a> ·
  <a href="https://docs.ophis.fi"><b>Docs</b></a> ·
  <a href="https://explorer.ophis.fi"><b>Explorer</b></a> ·
  <a href="https://docs.ophis.fi/ai-agents"><b>Agents</b></a> ·
  <a href="packages/sdk"><b>SDK</b></a> ·
  <a href="SECURITY.md"><b>Security</b></a>
</p>

---

Say `swap 100 USDC for ETH on Base` and Ophis resolves the tokens, chain, and
amount, then fills the order through a competitive solver auction that settles
on-chain. It is a fork of [CoW Protocol](https://cow.fi) (orderbook, autopilot,
driver, and baseline solver) with a natural-language intent layer over a
rebranded CoW Swap UI. On Optimism, Ophis runs the whole stack under its own
settlement contracts and keeps the full fee; on the other supported chains
(Ethereum, Base, Arbitrum, and more) it routes through CoW Protocol's hosted
network.

What that buys you on every trade:

- **Gasless, MEV-protected.** Orders settle in a batch auction where every trade
  clears at one uniform price, so sandwiches and front-running are structurally
  absent, not best-effort.
- **Solver-aligned pricing.** On every supported chain the base fee is 1 bp and
  Ophis earns primarily when execution beats its reference quote: 80% of
  improvement on volatile pairs (99 bps cap), or 50% on stable pairs (20 bps
  cap). Hosted chains encode that policy in CIP-75 appData and separately pay
  CoW Protocol's upstream fees.
- **Non-custodial, no account, no auth.** Every order is signed in your own
  wallet (EIP-712 or ERC-1271). Ophis never holds keys or funds and cannot move,
  freeze, or recover them. The signature is the only trust boundary.
- **Transparent, capped fees.** A 0.01% (1 bp) base plus the capped improvement
  policy above, with a share returned monthly as WETH rebates plus an 8%
  referral on trades you bring.

**Live across 13 EVM chains**, with Ophis-operated settlement on Optimism
(chain 10), Unichain (130), and Robinhood Chain (4663), plus CoW-hosted
settlement on the other supported chains.

## Quickstart: the Intent API

Ophis's one bespoke API turns natural language into a structured order. No key,
no account, just POST your request:

```bash
curl -sS https://ophis.fi/api/intent \
  -H 'content-type: application/json' \
  -d '{"text":"swap 100 USDC for ETH on Base"}'
```

```json
{
  "ok": true,
  "data": {
    "intent": "swap",
    "entities": [
      { "type": "amount",    "value": "100",  "raw": "100",  "start": 5,  "end": 8 },
      { "type": "sellToken", "value": "USDC", "raw": "USDC", "start": 9,  "end": 13 },
      { "type": "buyToken",  "value": "ETH",  "raw": "ETH",  "start": 18, "end": 21 },
      { "type": "chain",     "value": "base", "raw": "Base", "start": 25, "end": 29 }
    ]
  }
}
```

Map the chain slug to a chain ID and hand the user a swap deep link to review and
sign. The endpoint only normalizes text, it never places, signs, or executes a
trade. It is rate-limited to 30 requests per minute per IP; non-browser callers
(no `Origin` header) are allowed, which is the path agents use. Full reference:
[docs.ophis.fi/intent-api](https://docs.ophis.fi/intent-api).

## Agents and SDK

Ophis is built to be traded by autonomous agents, not just people. Pick your
integration depth, all of it non-custodial and keyless:

### MCP server (recommended)

Point any MCP client (Claude, Cursor, a custom agent) at the hosted Model
Context Protocol server:

```
https://mcp.ophis.fi/mcp
```

It speaks Streamable-HTTP MCP and exposes 14 tools: intent parsing, canonical
token resolution, chain discovery, quoting, bounded order build/validation and
submission, rebate and integrator lookups, balances, portfolios, gas, charts,
and expected-surplus comparison. The server holds no keys and never signs.
`build_order` returns a bounded, ready-to-sign EIP-712 order with the receiver
pinned to the owner; the agent signs locally with its own key and submits. See
the [complete tool reference](apps/mcp-server/README.md#tools). (A bare request
without an `Accept: text/event-stream` header returns HTTP 406, that is the
transport negotiating, not an outage.)

### @ophis/sdk

For agents that build and sign CoW orders directly:

```bash
npm install @ophis/sdk
```

The SDK encodes four fork details that fail **silently** if you guess them:

- **`getOphisOrderbookUrl(chainId)`** picks the right host. Optimism self-hosts
  its orderbook (not `api.cow.fi`); the wrong host bypasses the Ophis solver and
  zeroes the fee.
- **`getOphisOrderDomain(chainId)`** gives the EIP-712 domain with the correct
  `verifyingContract`. The OP settlement is non-canonical, so the cow-sdk default
  is rejected on-chain.
- **`buildOphisAppDataPartnerFee(chainId)`** builds the exact CIP-75 volume-fee
  fragment `{ volumeBps, recipient }`, not the price-improvement shape.
- **`assertReceiverIsOwner(owner, receiver)`** pins the order receiver. An
  unpinned receiver is the number one drain vector for an automated signer.

### Discovery and the trust boundary

Ophis publishes machine-readable manifests for agent discovery under
`https://ophis.fi/.well-known/`: `mcp.json`, `ai-plugin.json`, `agent-skills/`,
and `api-catalog` (RFC 9727), plus the root-served `auth.md`, `llms.txt`, and
`openapi.json`.

These off-chain helpers make the safe path the easy path, but they are guards,
not an authorization boundary: a prompt-injected agent can ignore them. For an
agent that signs **without a human in the loop**, enforce policy where the agent
cannot reach it: funds in a Safe smart account, a deterministic policy gate
(allowlisted tokens, pinned receiver and appData, an oracle-bounded limit price,
spend caps), a guardian key, and the same policy checked again at orderbook
ingestion. Full guide: [docs.ophis.fi/ai-agents](https://docs.ophis.fi/ai-agents).

## Status

Ophis settles across two kinds of chains.

**Ophis-operated** (self-hosted orderbook, solver, and settlement; Ophis keeps the
full fee):

| Chain | Chain ID | Status |
|---|---|---|
| Optimism | 10 | **Live**: settlement, solver, partner fee |
| Unichain | 130 | **Live**: settlement, solver, partner fee |
| Robinhood Chain | 4663 | **Live**: settlement, solver, partner fee |

**CoW-hosted** (orders route through CoW Protocol's settlement and solver network,
with the partner fee disbursed by CoW): Ethereum, Base, Arbitrum, Polygon, BNB,
Gnosis, Avalanche, Linea, and the other CoW-supported chains, all live.

On **BNB Smart Chain (BSC, chain ID 56)** Ophis is live: orders placed through Ophis
(`SupportedChainId.BNB` in [`cowSdk.ts`](apps/frontend/apps/cowswap-frontend/src/cowSdk.ts),
mapped from the `bnb` slug in [`chainMap.ts`](apps/frontend/apps/cowswap-frontend/src/ophis/components/intent/chainMap.ts))
settle on-chain through CoW Protocol's GPv2Settlement at
`0x9008D19f58AAbD9eD0D60971565AA8510560ab41` on BSC, giving gasless, MEV-protected
swaps with no Ophis-side custody. Ophis does not deploy its own settlement on BSC;
BNB trades use CoW Protocol's canonical BSC deployment.

The two have different settlement contracts and orderbook hosts, so resolve them
per chain via `@ophis/sdk` or the MCP `list_chains` tool rather than assuming.
Full live status: [docs.ophis.fi/status](https://docs.ophis.fi/status).
Cross-chain destinations (Solana, Bitcoin) are surfaced via NEAR Intents.
Canonical contract addresses and the disclosure policy live in
[`SECURITY.md`](SECURITY.md).

## Architecture

| Path | Origin | Purpose |
|---|---|---|
| `apps/frontend/` | [`cowprotocol/cowswap`](https://github.com/cowprotocol/cowswap) (subtree) | Vite/Nx monorepo holding several surfaces: `apps/cowswap-frontend` is the swap UI (Ophis code under `src/ophis/` and `src/modules/mevReceipt/`), `apps/explorer` is the order explorer, `apps/ophis-landing` is the ophis.fi landing site. Self-contained pnpm workspace (own lockfile, excluded from the root). |
| `apps/backend/` | [`cowprotocol/services`](https://github.com/cowprotocol/services) (subtree) | Rust orderbook, autopilot, driver, baseline solver. Ophis additions live in dedicated crates and `ophis::` module paths. |
| `apps/mcp-server/` | New | `@ophis/mcp-server`: agent-facing MCP server (Streamable-HTTP) deployed as a Cloudflare Worker at `mcp.ophis.fi/mcp`. Holds no keys and never signs. |
| `apps/rebate-indexer/` | New | `@ophis/rebate-indexer`: off-chain volume-tier and WETH rebate indexer plus Safe batch proposer ([rebates.ophis.fi](https://rebates.ophis.fi)). |
| `apps/docs-ophis/` | New | Docusaurus docs portal ([docs.ophis.fi](https://docs.ophis.fi)). Self-contained app (own lockfile, excluded from the root, like `apps/frontend`). |
| `packages/sdk/` | New | [`@ophis/sdk`](packages/sdk): dependency-free helpers for the per-chain orderbook host, EIP-712 order domain, CIP-75 partner-fee `appData`, receiver-pinning guards,