Skip to main content

mishmar (Python)

Mishmar is a risk management layer for trading bots and AI agents: every order is checked against your limits before it reaches the exchange, large orders wait for your approval, and no key can trade alone.

This is the Python client: build a proposal, sign it with the agent's key, send it to the engine, read the decision; and read the connected accounts the agent was given.

The package also puts mishmar on the path, so uvx mishmar mcp runs the MCP server and uvx mishmar signer run the signer without the CLI installed: the command runs the binary found through MISHMAR_BIN, the PATH or ~/.mishmar/bin, and when there is none fetches the pinned release (v0.5.3) into ~/.mishmar/bin first, checked against the release's checksums.

from datetime import timedelta
from mishmar import AgentKey, Client, Proposal

key = AgentKey.parse("msk_…")           # shown once when the engine issued the key
client = Client("http://localhost:8080/v1", key, key_id="key_…")

decision = client.propose(Proposal(
    connected_account_id="ta_…", symbol="BTC", side="buy", size="0.25",
    order_type="market", valid_for=timedelta(minutes=5),
))
print(decision["verdict"])              # allow | require_approval | block

# Pull a resting order this agent placed through Mishmar: a cancel names the
# order by the clientOrderId its decision carries, and has no side or size.
client.propose(Proposal(
    connected_account_id="ta_…", symbol="BTC", kind="cancel",
    target_client_order_id=decision["proposal"]["clientOrderId"],
))

Sizes, prices and leverage are decimal strings and are signed exactly as written: "0.5" and "0.50" are the same quantity but different signatures. Never pass a float.

A call the engine did nothing with goes again by itself: 503 unavailable while the engine restarts and 429 rate_limited (after its Retry-After), for up to 45 s, then the last answer is raised as EngineError. Nothing else is retried. Client(..., retries=None) turns that off; retries=Retries(budget=90) tunes it.

Reading connected accounts

An agent reads each connected account it was given whole: balances, the venue's positions, transactions and value over time, whoever acted on the account. A connected account is one pool of money at a venue: a Binance connection has a Spot and a USDⓈ-M Futures account, a Hyperliquid address has Perps and Spot. Each names its connection, which holds it at the venue (the person's name for it, venueAccount, which main account or sub-account it is there, sync, how current its data is, and accountCount, how many accounts the connection has). The accounts' values add up to the connection's only when the agent was given all accountCount of them; otherwise the sum is of the accounts it can see. A move between two accounts of one connection is a transfer_out on one and a transfer_in on the other, each naming the other in counterpartConnectedAccountId. Every read is signed with the agent's key and shows in the account's access log. The agent's API key alone is enough: it names the engine and the key id (MISHMAR_ENGINE, or engine_url=, for a self-hosted engine), so a read agent, which has no signer, needs nothing else.

from mishmar import Client

client = Client.from_api_key()                    # $MISHMAR_API_KEY
for account in client.connected_accounts():
    connection = account["connection"]             # what holds it at the venue
    print(account["venue"], connection["name"], account["name"], account.get("equityUsd"))
    snap = client.account_balances(account["id"])  # at=… for a past moment

page = client.account_transactions("ta_…", since="2026-11-01T00:00:00Z", kind="trade", limit=200)
for t in page["items"]:
    origin = t.get("origin", {})                   # who placed a trade
    print(t["at"], t.get("symbol"), "mine" if origin.get("own") else origin.get("agentName", "outside"))
# page.get("nextCursor") → cursor=… for the page after

positions = client.account_positions("ta_…")       # the venue's net positions, whoever placed them
series = client.account_equity("ta_…", since="2026-10-01T00:00:00Z", resolution="day")

me() says who the key belongs to and connected_account(id) reads one account. Times are RFC 3339 strings or timezone-aware datetimes. The answers are plain dicts, typed for a checker in mishmar.data (BalanceSnapshot, AccountTransactionPage, …). positions() is something else: the agent's own book, what its orders through Mishmar opened. Signer has the same reads, through its child. Started with a read agent's key, the child polls nothing (it learns from GET /agent/me that the agent reads) and refuses order, cancel and the other calls a read agent does not make with a 403 EngineError, before anything is sent.

Contract 0.21.0 changed the account's shape: an account is one pool, so Balance.wallet is gone and no read takes a wallet; the account's kind and setup are its connection's (account["connection"]["kind"], ["setup"]), and so is sync (account["connection"]["sync"]); positions and transactions carry their market (perp, spot, …), balances their priceUsd, and a value leaves out the assets named in unpricedAssets.

Run the tests, which include the cross-language vectors in ../spec/vectors:

pip install -e ".[test]"
python -m pytest

The signer as a child process

With the mishmar binary installed (or fetched with download_binary), Signer runs it as a child process and the bot holds no secret: the child has the agent's key and shares, signs each proposal, and sends it one-shot where it can. Reads go through the child too.

from mishmar import Signer

with Signer() as s:                                   # ~/.mishmar/agent.json
    d = s.order("ta_…", "BTC", "buy", "0.001", price="79500")
    if d["verdict"] == "require_approval":
        d = s.wait(d["id"])
    s.cancel("ta_…", "BTC", d["proposal"]["clientOrderId"])

The child stops when this process ends, however it ends: it runs with --exit-on-stdin-close and a pipe on its stdin. To share one signer among several processes, or keep it connected across restarts, run it on its own (mishmar signer run --local unix:/run/mishmar/signer.sock) and attach with Signer.connect("unix:/run/mishmar/signer.sock"); stop() then leaves it running. One signer runs per config, so a second Signer() on a config in use fails and names the process that holds it.

Metadata

Release files for mishmar 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mishmar 0.5.3
File Size Uploaded Provenance Actions
mishmar-0.5.3.tar.gz 47.8 kB With provenance Details for mishmar-0.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mishmar 0.5.3
File Interpreter ABI Platform Actions
mishmar-0.5.3-py3-none-any.whl Python 3 none any Details for mishmar-0.5.3-py3-none-any.whl

Total release size: 83.5 kB

Release files / mishmar-0.5.3.tar.gz

Download URL mishmar-0.5.3.tar.gz
Size 47.8 kB
Tags Source
SHA-256 checksum
How to use checksums
347366fd2adfb6cfba8831e2ce29ca01db53ca6e6fa1e076bbb6d0b999b1b8de
BLAKE2b-256 checksum
How to use checksums
9a2af2c4677ccc05af0c751bca31c3dade6583e8e39df26b6ecffe4e81b489c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / mishmar-0.5.3-py3-none-any.whl

Download URL mishmar-0.5.3-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
033ea1d3502f43abc4d2afc01ab41091d5ec5f0652c6b5d8f99d8e827b7bc3ad
BLAKE2b-256 checksum
How to use checksums
5f3892885897996d3fecf2887faa24fa3b9d28b97824656524414c3e9ba0704b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for mishmar 0.5.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mishmar-0.5.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page