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.

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]]
- 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, 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 2.17.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.17.0
File	Size	Uploaded
tribulnation_sdk-2.17.0.tar.gz	74.0 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tribulnation-sdk 2.17.0
File	Interpreter	ABI	Platform	Reset
tribulnation_sdk-2.17.0-py3-none-any.whl 98.8 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 172.7 kB

Release files / tribulnation_sdk-2.17.0.tar.gz

Download URL	tribulnation_sdk-2.17.0.tar.gz
Size	74.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`2f4b4127f8233d2dfef96b12cf7287a6ee66f3c92f9ea6e64a6c38157c9548ba`
BLAKE2b-256 checksum How to use checksums	`ebb1c2c65f353ed434c1a76489c1c13d38db92d0806c72b608f92b4b302c635f`
Upload date	Oct 9, 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/84a6468f3e2b104e046e5b6baff90664db8d9b2f

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/84a6468f3e2b104e046e5b6baff90664db8d9b2f/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/37985220860/attempts/1

Artifact

Subject: tribulnation_sdk-2.17.0.tar.gz
SHA-256 checksum: 2f4b4127f8233d2dfef96b12cf7287a6ee66f3c92f9ea6e64a6c38157c9548ba Verifying attestations

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

Download URL	tribulnation_sdk-2.17.0-py3-none-any.whl
Size	98.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7c7219464bd02ec4b368db151ce3ecd2b3c07a356606948d3d0c354cece3b0b5`
BLAKE2b-256 checksum How to use checksums	`441356f6c787cd8e77fcd417457c885a4fcf6c10219965149bb8ffe8f0fe6874`
Upload date	Oct 9, 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/84a6468f3e2b104e046e5b6baff90664db8d9b2f

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/84a6468f3e2b104e046e5b6baff90664db8d9b2f/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/37985220860/attempts/1

Artifact

Subject: tribulnation_sdk-2.17.0-py3-none-any.whl
SHA-256 checksum: 7c7219464bd02ec4b368db151ce3ecd2b3c07a356606948d3d0c354cece3b0b5 Verifying attestations