Tribulnation SDK

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
- 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]]
- 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:

WalletSDK: deposit/withdrawal methods — docs/wallet.md
EarnSDK: yield instruments — docs/earn.md
ReportSDK: balance/position history, with provenance — docs/report.md

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), 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

Release files for tribulnation-sdk 2.5.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 2.5.0
File	Size	Uploaded
tribulnation_sdk-2.5.0.tar.gz	52.6 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tribulnation-sdk 2.5.0
File	Interpreter	ABI	Platform	Reset
tribulnation_sdk-2.5.0-py3-none-any.whl 73.8 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 126.4 kB

Release files / tribulnation_sdk-2.5.0.tar.gz

Download URL	tribulnation_sdk-2.5.0.tar.gz
Size	52.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`4217ba9751edc07a050ddcd64982f0ccc7466ee365d4f617c3d2b2796eba14b8`
BLAKE2b-256 checksum How to use checksums	`5e8b6338abb1e64157991f4450adb61bc9e4f63a39371ed5f66ec5124a62ea5c`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tribulnation/sdk
Publishing commit: github.com/tribulnation/sdk/tree/ed5379f53f03e38b676ec1cbefeba5af0668b710

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/ed5379f53f03e38b676ec1cbefeba5af0668b710/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/36149985649/attempts/1

Artifact

Subject: tribulnation_sdk-2.5.0.tar.gz
SHA-256 checksum: 4217ba9751edc07a050ddcd64982f0ccc7466ee365d4f617c3d2b2796eba14b8 Verifying attestations

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

Download URL	tribulnation_sdk-2.5.0-py3-none-any.whl
Size	73.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`670f95da09545e534a4af5e070ac6240bb8902ae262ad1377e96780c0ad727ad`
BLAKE2b-256 checksum How to use checksums	`8c1cc456ec585d7fab242cf693f2b3ae128df932334a0408606a41e70022c289`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tribulnation/sdk
Publishing commit: github.com/tribulnation/sdk/tree/ed5379f53f03e38b676ec1cbefeba5af0668b710

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/ed5379f53f03e38b676ec1cbefeba5af0668b710/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/36149985649/attempts/1

Artifact

Subject: tribulnation_sdk-2.5.0-py3-none-any.whl
SHA-256 checksum: 670f95da09545e534a4af5e070ac6240bb8902ae262ad1377e96780c0ad727ad Verifying attestations