Tribulnation SDK

PyPI Python versions License: MIT

Fully-typed, async Python SDK for crypto trading and data.

Market, Wallet, Earn, and Report are abstract interfaces implemented per exchange and chain. Code written against MarketSDK runs unchanged on dYdX, Hyperliquid, MEXC, or any other supported venue.

Installation

pip install tribulnation-sdk[dydx,hyperliquid,mexc]

See the support matrix for details on extras.

Trading Quick Start

from dotenv import load_dotenv
from tribulnation.sdk import MarketSDK, accounts

load_dotenv() # load credentials from .env file

sdk = MarketSDK({
  'mexc_account1': accounts.Mexc(api_key='$MEXC_API_KEY', api_secret='$MEXC_API_SECRET'),
  # 'dydx', 'hyperliquid', and 'mexc' are available by default, even without listing them here
})
mexc = await sdk.market('mexc_account1:spot:BTCUSDT')
dydx = await sdk.market('dydx:perp:BTC-USD')

async with mexc.trades_stream() as my_trades:
  async for my_trade in my_trades:
    print(f'Hedging {my_trade}')
    await dydx.place_order({
      'type': 'LIMIT',
      'qty': -my_trade.qty,
      'price': my_trade.price,
    })

accounts.<Venue>() reads credentials from environment variables named after each field (accounts.Mexc() reads $MEXC_API_KEY/$MEXC_API_SECRET) — pass explicit values or other $VAR names to override.

Market IDs & Scoping

<account_id>:<exchange_id>:<market_id>, e.g. mexc_account1:spot:BTCUSDT. account_id is the key you registered in accounts — not necessarily the venue's own name — so you can run several accounts on one venue side by side. Equivalent ways to reach a market:

await sdk.depth('mexc_account1:spot:BTCUSDT')

venue = await sdk.venue('mexc_account1')
await venue.depth('spot:BTCUSDT')

exchange = await venue.exchange('spot')
await exchange.depth('BTCUSDT')

market = await exchange.market('BTCUSDT')
await market.depth()

Hold a Market reference in hot loops; use the scoped one-shot calls otherwise.

Market Interface

  • Public data:
    • depth() -> Book
    • depth_stream() -> AsyncContextManager[AsyncIterable[Book]]
    • rules() -> Rules: tick/step size, fees, min/max, rounding helpers
  • User data:
    • query_order(id) -> OrderState | None
    • open_orders() -> Sequence[OrderState]
    • trades_history(start, end) -> AsyncIterable[Sequence[Trade]]
    • trades_stream() -> AsyncContextManager[AsyncIterable[Trade]]
    • position() -> Position
    • available_notional() -> Decimal: max. notional you could open now
  • Trading:
    • place_order(order) -> OrderResponse
    • place_orders(orders) -> Sequence[OrderResponse]
    • cancel_order(id)
    • cancel_orders(ids)
    • cancel_open_orders()
  • Perpetual markets:
    • index() -> Decimal
    • next_funding() -> FundingRate
    • funding_rates(start, end=None) -> AsyncIterable[Sequence[FundingRate]]: market-wide rate history
    • funding_payments(start, end) -> AsyncIterable[Sequence[FundingPayment]]: your own settled cashflows
    • perp_position() -> PerpPosition: includes entry price

Full reference: docs/market/index.md, with per-venue notes for dYdX, Hyperliquid, and MEXC.

Mutating methods also take an optional settings dict for venue-specific options, keyed by venue:

await dydx.place_order({
  'type': 'LIMIT', 'qty': 0.01, 'price': 60_000,
}, settings={'dydx': {'order_flags': 'SHORT_TERM', 'short_term_gtb': 2}})

Other SDKs

Same account-mapping shape as MarketSDK:

Every SDK object is an async context manager; declare what you own with resources(), never __aenter__. Details: docs/lifecycle.md.

Error Handling

All errors subclass Error: NetworkError, ValidationError, ApiError (BadRequest, AuthError, RateLimited), LogicError.

Context, Logging & Retries

SDK calls are plain by default — no logging, no retries. Wrap them in a Context to add both:

from tribulnation.sdk import Context, NetworkError, RateLimited

ctx = Context().retried(NetworkError, RateLimited, max_retries=5).logged()
with ctx.use():
  await sdk.place_order('mexc_account1:spot:BTCUSDT', {'type': 'LIMIT', 'qty': 0.01, 'price': 60_000})

Retries back off exponentially and only wrap plain async calls, not streams or paginated history. Nested SDK calls each re-apply the active context, so retries can compound across scoping layers. Details: docs/context.md.

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for m4rs from gravatar.com m4rs

Credits

Author: Marcel Claramunt

License

MIT License (MIT License)

Requires

Python >=3.10

Provides Extra

mexc dydx hyperliquid binance bitget bit2me ethereum kraken bybit bingx

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tribulnation_sdk-1.7.2.tar.gz (41.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tribulnation_sdk-1.7.2-py3-none-any.whl (57.8 kB view details)

Uploaded Python 3

File details

Details for the file tribulnation_sdk-1.7.2.tar.gz.

File metadata

  • Download URL: tribulnation_sdk-1.7.2.tar.gz
  • Upload date:
  • Size: 41.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.11.15

File hashes

Hashes for tribulnation_sdk-1.7.2.tar.gz
Algorithm Hash digest
SHA256 d3832fbfc3237ff6d61ca1a5289756858c41c9c543c3d3172b4297b4e5a60e64
MD5 c48d66f695cb03ac2b6f6a49342fe840
BLAKE2b-256 43c7e21d30b2afada479f2787597c72968545321b1e77144f19b3959653b9fc8

See more details on using hashes here.

File details

Details for the file tribulnation_sdk-1.7.2-py3-none-any.whl.

File metadata

File hashes

Hashes for tribulnation_sdk-1.7.2-py3-none-any.whl
Algorithm Hash digest
SHA256 8090f7b85d9d3c478f689aae79c6e077f70a4a4ec4cced1ddb24536eb50f1a61
MD5 269d31d959dbc5a890b35040d315350a
BLAKE2b-256 3049de2bd3dacf57caad1df4adff1451a1b240cb4261f9644235d697ff6a2f73

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.7.2 This release

2 files

1.7.1

2 files

1.7.0

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.0

2 files

1.1.15

2 files

1.1.14

2 files

1.1.13

2 files

1.1.12

2 files

1.1.11

2 files

1.1.10

2 files

1.1.9

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page