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.

Today this repo holds opcode_sdk. The MCP server lands on top of it.

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.embedded)
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.

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.

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.