Skip to main content

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.

Standalone gateway

Install tribulnation-sdk[gateway] for tn gateway and the remote ProxySDK. Venue adapters are installed separately on the server. See the gateway guide for configuration, supported operations and migration details.

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
    • candles(interval, start, end) -> PaginatedResponse[Candle]: trade candles opening in [start, end), with timezone-aware bounds and no ordering guarantee; CANDLE_INTERVALS says which widths a venue serves
  • User data:
    • query_order(id) -> OrderState | None
    • open_orders() -> Sequence[OrderState]
    • trades_history(start, end) -> AsyncIterable[Sequence[Trade]]
    • trades_stream() -> AsyncContextManager[AsyncIterable[Trade]]
  • Spot markets (is_spot(market)):
    • rules() -> SpotRules: also names the pair's base and quote asset IDs
    • balances() -> SpotBalances: base and quote total and free (without order holds)
    • collateral_ids() -> SpotCollateralIds: what a buy (quote) and a sell (base) reserve on
  • Trading:
    • place_order(order) -> OrderResponse
    • place_orders(orders) -> Sequence[OrderResponse | Exception]: one result per order
    • 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 and the venue's estimated liquidation price (ADR 0068)
    • position() -> Position, collateral() -> PerpCollateral, leverage() -> Decimal
    • available_notional() -> Decimal: max. notional you could open now
    • remaining_position_limit() -> RemainingPositionLimit: per direction, how much more the venue's position limits let the position grow (ADR 0062)
    • collateral_id() -> str: the money funding new orders, shared with spot on unified accounts
  • sdk.collateral(id) -> Collateral: resolves any collateral ID (ADR 0051)
  • Balance, position, collateral, leverage, available-notional, ticker, perpetual-stats and next-funding reads take ttl: timedelta | None: None (default) asks the venue afresh, a timedelta accepts a shared answer that recent (ADR 0054)

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': {'flags': 'SHORT_TERM', 'short_term_gtb': 2}},
)

Other SDKs

Same account-mapping shape as MarketSDK:

Every SDK object is an async context manager: call methods on it directly, or enter it with async with to close its connections at a point you choose. Details: Async Usage.

Error Handling

All errors subclass Error: NetworkError, ValidationError, ApiError (BadRequest, AuthError, RateLimited, OrderRejected), 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: Context, Logging & Retries.

License

MIT

Metadata

Release files for tribulnation-sdk 4.2.0

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

Source distribution (sdist)

Source distribution for tribulnation-sdk 4.2.0
File Size Uploaded Provenance Actions
tribulnation_sdk-4.2.0.tar.gz 99.4 kB With provenance Details for tribulnation_sdk-4.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tribulnation-sdk 4.2.0
File Interpreter ABI Platform Actions
tribulnation_sdk-4.2.0-py3-none-any.whl Python 3 none any Details for tribulnation_sdk-4.2.0-py3-none-any.whl

Total release size: 224.1 kB

Release files / tribulnation_sdk-4.2.0.tar.gz

Download URL tribulnation_sdk-4.2.0.tar.gz
Size 99.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ef5dca8fa7196d474141090162e165178ca57a8d3f8b413e7476eb5d4bbad795
BLAKE2b-256 checksum
How to use checksums
29da7dbbccbf455eca5629b07a131e1fb74de7ed1e9ae245e138d75dc7b64d31
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 19, 2026.

Transparency log

Release files / tribulnation_sdk-4.2.0-py3-none-any.whl

Download URL tribulnation_sdk-4.2.0-py3-none-any.whl
Size 124.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
597006f32a22e8fb0674123d2339db7146254bb27e2c937e20007d85331c8b80
BLAKE2b-256 checksum
How to use checksums
b0a271b67e7f7fb0b776c7992bcb18716e15b43407a15f07c8a98ceead6b7cfe
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 19, 2026.

Transparency log

Security for tribulnation-sdk 4.2.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.

Full provenance

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

Select from 2 files

Attestation for tribulnation_sdk-4.2.0.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 19, 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.

Release history Release notifications | RSS feed

This release

4.2.0 This release

2 release files Full provenance

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