mcp-opcode

Python SDK for the opcode gasless trading API, and the MCP server built on top of it. It lets an agent, bot or script do what a user does in the opcode app — over plain HTTP, with its own wallet.

This repo holds two things: opcode_sdk, the client library, and opcode_mcp, an MCP server built on it that lets an AI agent trade with its own wallet under human approval.

Design

• Sign-then-submit. The client never holds a private key. Every signed action is two calls: prepare_X(...) returns the exact EIP-712 / EIP-7702 payload(s) to sign, the caller signs them with whatever custody they have, and submit_X(prepared, sig) POSTs the result. OpcodeClient takes no signer.

• No EVM RPC. Everything needed to build a signature comes off the quote or the session — the authorization nonce and the approve nonce are both carried in the quote descriptor. The SDK never opens a node connection.

• Trusted values are pinned, not accepted. Chain id, gateway and approve-delegate are checked against client-side constants before anything is signed, so a compromised backend cannot get a signature over an address of its choosing. See TrustedValues.

• Guards run before the key is touched. A quote that failed the server's safety verdict, is over the effective cap, or no longer has enough of its submit window left is refused at prepare_order() — not after a signature exists.

• Typed errors. Every wire error kind maps to an exception class chosen for what the caller should do about it, so retry-vs-fatal is a type, not a string match.

• Sync first. Built on httpx.Client.

Session token rides in the x-opcode-session header, held in memory only.

Related MCP server: seashail

Install

uv sync

Usage

from opcode_sdk import OpcodeClient, KeystoreSigner, EnvPassword, WalletKind, TrustedValues

client = OpcodeClient("https://app.opcode.fi", chain_id=1)
signer = KeystoreSigner("wallet.json", EnvPassword("OPCODE_KEYSTORE_PASSWORD"))

prep = client.auth.prepare_login(signer.address)
client.auth.submit_login(prep, signer.sign_typed_data(prep.signable))

quote = client.trade.quote(token_in, token_out, amount_in, wallet=WalletKind.privy)
order = client.trade.prepare_order(quote, trusted=TrustedValues.mainnet())
sigs = {
    k: (signer.sign_authorization(s) if k == "authorization" else signer.sign_typed_data(s))
    for k, s in order.signables.items()
    if s is not None
}
res = client.trade.submit_order(order, sigs)

OpcodeWallet(client, signer) wraps these into one-call flows (login, accept_terms, trade, wait_for_order) and re-logs in automatically on a 401.

WalletKind.privy is the default and the kind an agent wants: it is the only one that always returns the gasless approve grant, on any token. injected and unknown return permit or self_approve instead — a wallet-side or user-paid on-chain step the SDK cannot produce, and prepare_order() refuses them with GrantMethodUnsupported before touching the key.

Custody

KeystoreSigner reads a standard V3 eth-keystore and is the default. Two things are hooked separately, so you can replace either without the other:

• PasswordSource — where the password comes from. EnvPassword, FilePassword, PromptPassword, or your own callable.

• UnlockGate — whether a given signature is allowed to happen at all. AlwaysUnlocked, ConfirmEachSignature, CachedConfirmation, or your own. The gate is handed a SignRequest describing what is about to be signed, and raises UnlockDenied to refuse.

For any other custody (HSM, remote signer, MPC, hardware) implement the Signer protocol — sign_typed_data and sign_authorization — and pass it anywhere a signer is taken. Nothing in the SDK reaches for a key on its own.

An EIP-7702 authorization is called out as its own SignKind: it delegates the EOA's code and is not something a gasless client can undo, so a gate can treat it differently from an ordinary order signature. CachedConfirmation never caches it.

Surfaces

client.auth, .onboarding, .market, .account, .compliance, .explorer, .trade, .feed, .recipients.

Buys, sells and withdrawals all go through the same quote-and-sign path — a withdrawal is a same-token swap to another receiver. Paying an address other than the signer requires that address to be in the recipient book first (client.recipients), and the book's entries are re-verified locally against your own signature rather than trusted as returned.

Membership and terms status are read from GET /api/session; there are no standalone /invite/status, /terms/status or /session_limits endpoints.

tradable_now() answers whether an asset can be traded right now from the catalog entry plus market status. It is a client-side read of side-collapsed data and cannot see a per-side halt; a quote is the only authority.

MCP server

export OPCODE_KEYSTORE=~/path/to/wallet.json
export OPCODE_KEYSTORE_PASSWORD_FILE=~/path/to/wallet.pass   # or OPCODE_KEYSTORE_PASSWORD
uv run opcode-mcp

One wallet per process — there is no wallet selector, so an agent cannot be talked into paying from the wrong account. Two wallets means two servers.

Value-moving tools are two calls, and the human approves a bound rather than a price. opcode_place_order signs nothing; it freezes an intent and returns a handle plus a summary to show a person. That summary states a minimum received, which the chain enforces. When opcode_confirm_order runs it takes a fresh quote, requires it to clear the frozen minimum, and only then signs. So the 60-second signing window is entered and left entirely machine-side, and a human who takes their time cannot be punished for it.

An approval is single-use and expires. Failures raise, so the protocol marks them isError, and each carries a retry discriminant (never / after / requote / fix_input / human) so an agent can tell a fatal from a transient without parsing prose.

opcode_withdraw requires the destination to already be in the recipient book — vetting an address and paying it are separate decisions, each with their own approval.

Tests

uv run pytest

The suite pins the EIP-712 digests, the order meta bit packing, the grant plan, and the tradability gate. It makes no network calls.