Python SDK: Proof Exchange Client and Action Builders

pip install proof-trading-sdk

from proof_trading_sdk import (
    generate_keypair,
    pubkey_to_owner,
    owner_to_hex,
    hex_to_owner,
    chain_id_from_string,
    sign_and_encode,
    decode_tx,
    verify_signature,
    encode_signed_tx,
    SigningHandle,
    load_key_from_fd,
    load_key_from_pkcs11,
)

from proof_trading_sdk import load_key_from_fd, load_key_from_pkcs11, SigningHandle

# Load from a file descriptor (e.g. a sealed pipe or tmpfs mount)
handle: SigningHandle = load_key_from_fd(fd_number)

# Load via PKCS#11 (HSM / TPM / cloud KMS)
handle: SigningHandle = load_key_from_pkcs11(library_path, slot_id, pin)

from proof_trading_sdk import (
    Side, TimeInForce,
    PlaceOrder, MarketOrder,
    CancelOrder, CancelClientOrder, CancelAllOrders,
    CancelReplaceOrder, AmendOrder,
    ClosePosition, ApproveAgent, RevokeAgent,
    OracleUpdate, Deposit, Withdraw, WithdrawRequest,
    ConfirmDeposit, ConfirmWithdrawal, FailWithdrawal,
    ResolveEvent, FailDeposit, SetUserMarketLeverage,
    CreateMarket, CreateImpactMarket, UpdateMarketFees,
    SetAccountFeeOverride, RunLiquidationSweep, RunFundingTick,
    RawAction, FEE_OVERRIDE_REVERT_SENTINEL,
    encode_action, decode_action,
)

# Encode any Action to (action_type_int, payload_bytes) via the Rust core
action_type, payload = encode_action(PlaceOrder(...))

# Decode raw payload bytes back to a field dict
fields = decode_action(action_type, payload)

from proof_trading_sdk import (
    ProofTradingSdkError,
    AuthenticationError,
    CodecError,
    EngineError,
    GatewayError,
    RateLimited,
    SigningError,
    TransportError,
    get_error_name,
    get_error_code_table,
)

ProofTradingSdkError
├── CodecError          — MessagePack encode/decode failure
├── SigningError        — Ed25519 key load or signing failure
├── AuthenticationError — HTTP 401 / 403 (invalid or missing API key)
├── EngineError         — Engine rejection with a typed error code
│       .code: int      — e.g. 21 for InvalidNonce
│       .name: str      — canonical name from the Rust manifest
│       .message: str   — human-readable description
├── TransportError      — HTTP/WebSocket connection, DNS, or timeout error
│       .status_code: int | None
│   └── GatewayError    — Gateway 5xx; retry with backoff
│           .body: str
└── RateLimited         — HTTP 429
        .retry_after_secs: float
        .bucket: str

# Look up a canonical error name by code
get_error_name(21)           # → "InvalidNonce"

# Get the full manifest from the Rust core — [{code, name, meaning}, ...]
table = get_error_code_table()

from proof_trading_sdk import NonceAllocator

alloc = NonceAllocator()
seq = alloc.allocate()   # → current millisecond timestamp, monotonically increasing

from proof_trading_sdk import ExchangeClient, PlaceOrder, Side, TimeInForce

client = ExchangeClient(
    gateway_url="https://api.dev.proof.trade",
    api_key="<your-api-key>",
    secret_key=private_key_bytes,   # 32-byte Ed25519 seed
    chain_id=chain_id_bytes,        # 32-byte chain binding
)

# Encode + sign + submit in one call
result = client.submit(PlaceOrder(
    market=1,
    owner=bytes.fromhex("<owner-hex>"),
    side=Side.Buy,
    price=50_000_000,   # micro-USDC per contract
    quantity=10,
    time_in_force=TimeInForce.Gtc,
))

# Or sign manually and submit the raw envelope bytes
envelope = client.sign_action(action)
result = client.submit_action(envelope)

account  = client.account()                 # AccountState: balances, positions, open_orders
orders   = client.open_orders(owner_bytes)
markets  = client.markets()
book     = client.orderbook(market_id)
ticker   = client.ticker(market_id)         # → dict | None
health   = client.health()
status   = client.status()

# History (time-windowed)
deposits     = client.history_deposits(owner_bytes, from_ms=..., to_ms=..., limit=100)
withdrawals  = client.history_withdrawals(owner_bytes)
resolutions  = client.history_resolutions(owner_bytes, impact_market_id=5)

# Cursor-paginated history
fills_page   = client.history_fills(owner_bytes, limit=50)
funding_page = client.history_funding(owner_bytes)

import os
from proof_trading_sdk import (
    ExchangeClient,
    generate_keypair,
    pubkey_to_owner,
    chain_id_from_string,
    PlaceOrder,
    Side,
    TimeInForce,
)

# 1. Load or generate a keypair
seed = bytes.fromhex(os.environ["PROOF_PRIVATE_KEY"])
kp = generate_keypair(seed)
owner = pubkey_to_owner(kp["public_key"])

# 2. Resolve the chain ID (or pin it explicitly)
chain_id = chain_id_from_string("proof-devnet-1")

# 3. Build the client
client = ExchangeClient(
    gateway_url="https://api.dev.proof.trade",
    api_key=os.environ.get("PROOF_API_KEY", ""),
    secret_key=seed,
    chain_id=chain_id,
)

# 4. Check connectivity
print(client.health())

# 5. Place a limit buy on market 1
result = client.submit(PlaceOrder(
    market=1,
    owner=owner,
    side=Side.Buy,
    price=50_000_000,   # 50.00 USDC in micro-units
    quantity=1,
    time_in_force=TimeInForce.Gtc,
))

print(result)   # {"code": 0, "tx_hash": "...", ...}

from proof_trading_sdk import ExchangeClient, load_key_from_fd
import os

# Open the key file and pass the fd number — never read the bytes in Python
key_fd = os.open("/run/secrets/proof_signing_key", os.O_RDONLY)
handle = load_key_from_fd(key_fd)
os.close(key_fd)

client = ExchangeClient(
    gateway_url="https://api.dev.proof.trade",
    key_handle=handle,   # key_handle takes precedence over secret_key
    chain_id=chain_id,
)

# Signing happens entirely in Rust — the key never touches Python's heap
result = client.submit(action)