@ophis/sdk

Version 0.4.5 refreshes the Arc fee-policy and trader-enrollment documentation. Runtime behavior and exported types are unchanged from 0.4.4.

Integration helpers for Ophis — a CoW Protocol fork with a natural-language intent layer.

Non-custodial. These helpers build and guard order parameters. They never hold keys or sign on your behalf. See Security before wiring up an automated signer.

The SDK builds orders for configured EVM settlement deployments. The standalone swap app also supports externally funded NEAR swaps, including Bitcoin and Solana sources; those deposits are a separate flow and are not built or signed by these order helpers. See network and funding coverage.

Install

npm install @ophis/sdk

What's in it

• getOphisOrderbookUrl(chainId) — the correct orderbook host per chain. Optimism, Unichain, Robinhood Chain, and Arc use Ophis-operated hosts, not api.cow.fi; getting this wrong bypasses the intended Ophis settlement path.
• getOphisOrderDomain(chainId) / getOphisSettlementAddress(chainId) — the EIP-712 signing domain with the correct per-chain verifyingContract (all four Ophis-operated settlements are non-canonical, so the cow-sdk default is wrong there).
• buildOphisAppDataPartnerFee(chainId, isStablePair) — the exact CIP-75 fee config. Operated chains return the 1 bp base (their backend adds improvement capture when configured); hosted chains return base + pair-aware capped improvement entries.
• ophisOrderReceiver / assertReceiverIsOwner — pin a CoW order's receiver to the owner. An unpinned receiver is the #1 drain vector for an automated signer.
• buildOphisOrderMetadata / enrollOphisTrader / buildOphisOrderCreation — the high-level order-flow helpers: appCode is always 'ophis' (a custom one silently forfeits the rebate), the receiver is asserted, and the sendOrder wire shape (full appData string + appDataHash) is correct. Call await enrollOphisTrader(owner, { blocking: true }) separately before each submission, including delayed vault trades; constructing metadata or an order does not enroll the wallet. Use the actual order owner (the Safe for a vault), not its curator.
• getOphisVaultRelayer(chainId) — the correct approve spender for the one-time sell-token approval. On Ophis-operated chains the relayer is not cow-sdk's canonical one, so resolve it here.
• buildOphisEthFlowOrder / getOphisEthFlowAddress / isOphisEthFlowChain — sell native ETH through Ophis via the on-chain eth-flow createOrder, with the Ophis partner-fee appData embedded. Without this an integrator has to wrap to WETH first and Ophis is unavailable on native-ETH sells. The builder pins the receiver to the taker, hardcodes the eth-flow feeAmount/msg.value correctly, and (optionally) verifies the committed appData hash binds to the JSON you upload.
• parseOphisApiError / withOphisRetry / isUnroutable / isRetryable: typed errors for the orderbook API's numeric code bands (1xxx-5xxx) with traceId capture (X-Trace-Id header + error body). "No route" is a typed answer (OphisUnroutableError), not a failure, and is never retried; 429 is never retried in-call (both hold even under a custom shouldRetry: the terminal classes are rethrown before the predicate runs; for every other error a custom predicate replaces the default policy entirely and can narrow or broaden it, so broadening callers must retry only transient failures); only the 3xxx upstream band (503 + Retry-After) is. Unknown codes degrade gracefully and preserve the raw payload.
• ophisPreflight / isPreflightReady / approvalNeeded: one batched Multicall3 balanceOf + allowance read answering "can this order settle?" before the user signs. Takes any viem PublicClient (structural interface, no viem runtime dependency), defaults the spender to the correct per-chain vault relayer, and fails closed: an RPC failure throws (including an outage that viem surfaces as an all-failure batch), it never reports ready, the batch is one un-chunked eth_call (single block snapshot) on clients that honor batchSize: 0 (viem PublicClients do unless constructed with an explicit client-level batch.multicall.batchSize, which viem lets override the per-call value; clients that chunk anyway are covered by pair-consistency and transport-shape guards that throw instead of zeroing), and when the client exposes getChainId (viem's does) a client connected to a different chain than the requested chainId throws instead of returning plausible wrong-network balances.
• assignTier, ophisDefaults, and the partner-fee constants.

Example

SDK 0.4.4 enables referral tags on Arc (5042), which is covered by the rebate indexer. Arc applies the standard 1 bp base plus capped backend improvement capture on in-market orders. Enroll the trader and supply a valid referral code for attribution on eligible settled orders. isOphisFeeChain reports fee support, not reward eligibility; buildOphisReferrerMetadata only formats the tag.

import {
  getOphisOrderbookUrl,
  getOphisOrderDomain,
  buildOphisAppDataPartnerFee,
  assertReceiverIsOwner,
} from '@ophis/sdk';

const orderbook = getOphisOrderbookUrl(10);          // https://optimism-mainnet.ophis.fi
const domain = getOphisOrderDomain(10);               // { name, version, chainId, verifyingContract }
const partnerFee = buildOphisAppDataPartnerFee(chainId, isStablePair);

assertReceiverIsOwner(owner, order.receiver);         // throws if proceeds would leave the account

Security

These are off-chain misuse guards, not an authorization boundary — they make the safe path the easy path, but a caller can ignore them. For an agent that signs without a human in the loop, enforce policy on-chain (a Safe + an EIP-1271 policy validator: pinned receiver, pinned appData/hooks, an oracle-bounded limit price, spend caps, and a guardian). See the AI agent integration guide.

License

GPL-3.0-or-later