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>Choose tokens, review the quote, and authorize your swap.</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>

---

Select tokens and networks in the swap app, review the quote, and authorize
the displayed flow. The optional Intent API parses requests such as
`swap 100 USDC for ETH on Base`; it does not execute them. Batch-auction
orders settle onchain through configured solver routes. 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, Unichain, Robinhood Chain, and Arc, 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.

For standard batch-auction orders:

- **Gasless, MEV-protected.** Orders settle in a batch auction where every trade
  uses uniform prices per token pair. Offchain submission and signed limits
  mitigate common MEV; they do not eliminate every execution risk.
- **Solver-aligned pricing.** On every supported chain the base fee is 1 bp.
  Ophis also earns 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), or explicitly presigned onchain. Standard ERC-20
  orders keep funds in the wallet until settlement; native-token, bridge and
  external OTC flows can require deposits and have separate recovery rules.
- **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 indexed chains, including Arc.

**Live across 14 EVM chains**, with Ophis-operated settlement on Optimism
(chain 10), Unichain (130), Robinhood Chain (4663), and Arc (5042), plus CoW-hosted
settlement on the other ten chains. Arc applies the same capped backend improvement policy for in-market orders; eligible settled trades are covered by rebate indexing.

## 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 13 tools: intent parsing, canonical
token resolution, chain discovery, quoting, bounded order build/validation and
submission, integrator volume and fee 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).
The standalone app also supports Bitcoin, Solana, Monad, Hyperliquid (Hypercore),
X Layer, Sui, Tron, Starknet and Zcash as NEAR sources and destinations where live
assets and quotes permit. Selecting an external source opens a deposit flow in
the same swap form: review the quote and source-chain refund address, confirm,
then fund the specified deposit before its deadline with any required memo.
This is separate from SDK/MCP EVM order building. See
[networks and funding coverage](https://docs.ophis.fi/networks-assets).
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