tickwire (Python SDK)
Typed clients for the Tickwire MT4/MT5 API: one API for both platforms, truthful health, idempotent trading, an audit trail, agent keys with pre-trade hooks, and signed webhooks. Sync and async.
Not published yet. pip install tickwire won't find it. Install from source, from the
repository root:
pip install ./sdk/python
Once it is published:
pip install tickwire
Python 3.11 or newer. MIT licensed. Docs: tickwire.io/docs/sdk-python.
Quick start
A free sandbox (no sign-in, no card) against the public API, then a first trade:
from tickwire import Tickwire, sandbox_signup, trade_succeeded
API = "https://api.tickwire.io"
sb = sandbox_signup(API) # a twsk_ key (shown once: keep it) and one simulated MT5 account
with Tickwire(API, sb["apiKey"], actor="quickstart") as tw:
acc = tw.account(sb["account"]["id"]) # MT4 and MT5 look the same
print(acc.health()["status"]) # healthy | stale | disconnected | down
print(acc.price("EURUSD"))
r = acc.market_order("EURUSD", 0.01, reason="quickstart") # Idempotency-Key generated for you
print(trade_succeeded(r), r["numericCode"])
sandbox_signup is anonymous and rate limited (5 sandboxes an hour per
address), so call it once and reuse the key. With your own API key, skip it:
Tickwire("https://api.tickwire.io", "YOUR_API_KEY"), or set
TICKWIRE_API_URL and TICKWIRE_API_KEY and call Tickwire(). Then
tw.list_accounts() lists your accounts.
sandbox=True reads the sandbox URL from sandbox_url= or
TICKWIRE_SANDBOX_URL (it never guesses a host) and raises ConfigError if
neither is set.
60 seconds: an AI agent with its own key
The account owner creates a scoped agent key; the agent can then trade only
through the guarded path (kill switches, the owner's pre-trade hook, audit).
This needs your own API key: the restricted key from sandbox_signup cannot
create agent keys.
from tickwire import AgentClient, Tickwire
API = "https://api.tickwire.io"
with Tickwire(API, "YOUR_API_KEY") as owner:
created = owner.create_agent_key("my-agent", [account_id], reason="new agent")
agent_key = created["key"] # twag_…, shown once: store it now
with AgentClient(API, agent_key) as agent:
r = agent.trade(account_id, {"actionType": "ORDER_TYPE_BUY", "symbol": "EURUSD", "volume": 0.01},
reason="breakout above the Asian range")
if r.outcome == "applied":
print("filled", r.evidence)
elif r.outcome == "held":
print("waiting for approval", r.hold_id)
elif r.outcome == "rejected":
print("not executed:", r.error, "sent:", r.sent)
else: # unknown: it MAY have executed
print(agent.trade_status(r.idempotency_key)) # never retry with a new key
Async: AsyncTickwire and AsyncAgentClient have the same methods
(async with …, await …), plus resumable streams:
async with AsyncTickwire(API, "YOUR_API_KEY") as tw:
async with tw.account(account_id).stream() as s: # stream protocol v2
state = await s.wait_synchronized()
s.on("positionUpdated", lambda frame, st: print(frame["position"]))
What it covers
| Area | Methods |
|---|---|
| Native account (MetaApi-compatible) | account(id): health, capabilities, audit, snapshot, account_information, positions, position, orders, order, deals, deals_by_position, history_orders, symbols, price, tick, specification, server_time, trade, check_trade, market_order, close_position, stream |
| Control plane | list_accounts, get_account, list_webhooks, get_webhook, create_webhook, delete_webhook |
| Webhooks v2 | webhook_event_types, webhook_settings, update_webhook, enable_webhook, disable_webhook, rotate_webhook_secret, reveal_webhook_secret, list_webhook_deliveries, get_webhook_delivery, resend_webhook_delivery, resend_event; verify with verify_webhook(secret_or_secrets, headers, body) (all rotation secrets) or verify_standard_webhook |
| Agent administration | create_agent_key, list_agent_keys, get_agent_key, update_agent_key, revoke_agent_key, set_agent_key_kill_switch, list_kill_switches, set_account_kill_switch, create_pretrade_hook, list_pretrade_hooks, get_pretrade_hook, update_pretrade_hook, delete_pretrade_hook, rotate_pretrade_hook_secret, list_holds, get_hold, cancel_hold, agent_audit |
| Guarded execution | execute_trade (returns a TradeResult) |
| Sandbox, connected AI apps | sandbox_signup() (module function, no key needed), sandbox_info, create_sandbox_key, list_connected_apps, disconnect_connected_app |
| Dedicated IPs, billing | dedicated_ips, move_accounts_to_dedicated_ip, billing_summary (read-only) |
Agent API (AgentClient) |
me, accounts, snapshot, health, account_information, positions, orders, price, specification, deals, trade, trade_status, audit |
Pagination
Native /v1 lists (agent keys, pre-trade hooks, holds, kill switches, the
agent audit log, connected apps, AgentClient.accounts) return one page:
{"data" | "entries" | "apps" | "accounts": [...], "has_more", "next_cursor"}.
Pass limit= (1 to 500, default 100) and cursor=, or let pages follow the
cursor for you:
for page in tw.pages(tw.list_holds, status="pending", limit=100):
for hold in page["data"]:
...
# async: async for page in tw.pages(tw.list_agent_keys): ...
Snapshot
tw.account(id).snapshot() (or AgentClient.snapshot(account_id)) returns
account information, positions, orders, health and server time in one read,
each section with status (ok, stale, unavailable), read_at and
age_ms. The broker's UTC offset is explicit
(server_time["data"]["brokerUtcOffsetMinutes"], None when unknown).
Every call maps to an operation in tickwire/_operations.py, generated from
the public OpenAPI spec (tickwire.io/openapi.json).
Safety you get by default
- Idempotency. Every mutation sends
Idempotency-Key(yours, or a generatedtw_…),X-ActorandX-Reason. Passidempotency_key=to make a repeat of the same decision safe across restarts. - Retries only when safe. Reads retry on transport errors and
408/429/502/503/504 with full-jitter backoff (
Retry-Afterhonoured up to the cap), within a per-clientRetryBudgetso an outage cannot become a retry storm. A mutation retries only when the server confirms it did not run it, always with the same key: connection refused;409 idempotency_in_flight(the first attempt is still running, so the SDK waitsRetry-Afterand then gets that attempt's stored result); or a 429/5xx whose body says explicitlysent: false(error codes alone never count). unknownis never retried. A lost reply to a mutation (read timeout, reset) or any other 408/5xx raisesOutcomeUnknowncarrying the idempotency key; the guarded trades (execute_trade,AgentClient.trade) returnTradeResult(outcome="unknown", sent="unknown")instead.- Streams resume.
AccountStreamre-subscribes with the lastseq; a gap forces a full resync, so the mirror is never silently wrong. - Typed errors (
NotFound,Conflict,NotSupportedOnMt4,RateLimited,ConfigError, …) keep the server envelope in.body.health()returns the body of a 503: "down" is an answer, not an exception. - Webhooks:
verify_webhook(secret, headers, body)checks the HMAC-SHA256 signature and rejects replays outside a 5-minute window. - Clean close.
close()/aclose()release every connection and are idempotent. Credentials never appear inrepr().
A bare control plane (no gateway) serves the FxSocket routes at the root:
pass control_prefix="".
Examples
A prop-firm risk guard (flatten on daily drawdown), a trade copier, a journal sync and a trading bot: tickwire.io/docs/guides/examples. Demo accounts only.
Metadata
Release files for tickwire 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tickwire-0.1.0.tar.gz | 48.8 kB | Without provenance | Details for tickwire-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tickwire-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for tickwire-0.1.0-py3-none-any.whl |
Total release size: 83.6 kB
Release files / tickwire-0.1.0.tar.gz
| Download URL | tickwire-0.1.0.tar.gz |
|---|---|
| Size | 48.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d3824c5f7877c20ad96102acdf21fe628664ce90cd4f4da7f2a368d9c6d35b1a
|
|
BLAKE2b-256 checksum How to use checksums |
35e258ee6c1bd2ec2b1d1b1d02ed9b9bcec3a8356cf0032565fc412a5ac7cece
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / tickwire-0.1.0-py3-none-any.whl
| Download URL | tickwire-0.1.0-py3-none-any.whl |
|---|---|
| Size | 34.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e9618c2453625b612bfe8edc40faba59d9ac5ffcdbd4bffd9c90ba5ca3bceec3
|
|
BLAKE2b-256 checksum How to use checksums |
59fb82bad130d4cb59b9cb1fa80ca224a9a7ccac8fd91fdcf71cf66e6a6be6d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for tickwire 0.1.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.