noether-sdk

Official Python SDK for Noether — a decentralized perpetual exchange on Stellar / Soroban.

Async-first (httpx + pydantic), typed, mirrors the public surface of the TypeScript SDK (noether-sdk on npm).

Install

pip install noether-sdk
# Required for API-key issuance (keys.create) and local Keypair signing:
pip install "noether-sdk[stellar]"

Quick start — public reads

import asyncio
from noether_sdk import NoetherClient

async def main():
    async with NoetherClient("https://api.noether.exchange") as client:
        markets = await client.markets.list()
        btc = await client.oracle.get_price("BTC")
        print("BTC oracle:", btc.price_float)

asyncio.run(main())

Authed: account info

from noether_sdk.transport import Credentials

async with NoetherClient(
    "https://api.noether.exchange",
    credentials=Credentials("nk_...", "..."),
) as client:
    me = await client.account.me()
    mine = await client.account.positions()  # mine.positions (open) + mine.events

Issue an API key (one-shot)

Requires the stellar extra. keys.create wraps the gateway challenge as a manageData op on a placeholder transaction and asks your signer for a signature over the transaction hash — the SDK never sees the secret.

from stellar_sdk import Keypair

kp = Keypair.from_secret(os.environ["STELLAR_SECRET"])
async with NoetherClient("https://api.noether.exchange") as client:
    issued = await client.keys.create(
        address=kp.public_key,
        signer=lambda data: kp.sign(data),
        label="mm-bot-1",
    )
    print(issued.key_id, issued.secret)  # store immediately

Place an order — execute_trade

Trading needs collateral: fund your wallet with testnet USDC from the Noether faucet (Friendbot only provides XLM) before placing orders.

from stellar_sdk import Network, TransactionBuilder

def sign_xdr(xdr: str) -> str:
    tx = TransactionBuilder.from_xdr(xdr, Network.TESTNET_NETWORK_PASSPHRASE)
    tx.sign(kp)
    return tx.to_xdr()

prepared, submitted = await authed.execute_trade(
    {
        "op": "open_position",
        "asset": "XLM",
        "collateral": 1_000 * 10_000_000,
        "leverage": 2,
        "direction": "Long",
    },
    sign_xdr,
)
print(submitted.hash, submitted.status)

execute_trade calls orders.prepare → asks your signer for the signed XDR → calls tx.submit and polls until SUCCESS / FAILED / timeout.

Sub-client cheatsheet

WebSocket

from noether_sdk.ws import WsClient

ws = WsClient("wss://api.noether.exchange/v1/ws")
await ws.connect()  # returns on server hello; raises on timeout/failure
await ws.subscribe("ticker.BTC", lambda data, ch: print(ch, data["priceFloat"]))

WsClient reconnects automatically with exponential backoff and replays your login + active subscriptions on every reconnect (account.* channels are re-sent after each login ack). connect() raises instead of hanging when the gateway is unreachable (connect_timeout, default 15s); subscription rejections and failed logins surface through the on_rejected / on_login callbacks.

Errors

from noether_sdk import (
    AuthError, RateLimitError, BadRequestError, ServerError,
)

try:
    await client.markets.get("DOGE")
except BadRequestError as err:
    print("bad request:", err.body)
except RateLimitError as err:
    print("retry in", err.retry_after_sec)

Examples

• examples/place_order.py — Friendbot fund + key issuance + open_position end-to-end (fund the wallet with testnet USDC from the faucet first, or the open_position step will fail).
• examples/ws_ticker.py — minimal WebSocket subscription.

Dev

pip install -e ".[dev,stellar]"
pytest

Publish (maintainers)

# From sdk-py/ — do not put npm pack tarballs in dist/ (breaks twine).
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-...   # scope: entire account or project noether-sdk
./scripts/publish_pypi.sh

Status

REST surface complete + WS sub-client. Mirror of the TypeScript SDK shape so cross-language services can be written in either language without translation cost. See CHANGELOG.md.