Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Proof-labs/trading-sdk/llms.txt

Use this file to discover all available pages before exploring further.

The Proof Trading SDK is a first-party client library for the Proof Exchange, a CometBFT-based perpetuals exchange. It handles every layer between your application and the on-chain engine: Ed25519 key generation and signing, MessagePack wire encoding, monotonic timestamp-nonce allocation, and both gateway and direct CometBFT broadcast. Whether you are building a trading bot, an AI agent, or a full-featured frontend, every exchange action flows through a single submitTx call.

​
What the SDK does

The SDK packages four responsibilities into one cohesive interface:
  • Ed25519 signing — generate a keypair locally, derive a 20-byte owner address via pubkeyToOwner, and attach a domain-separated signature to every transaction.
  • MessagePack wire encoding — transactions are compact positional arrays ([version, action_type, seq, payload, pubkey, signature]) encoded with MessagePack, not JSON.
  • Timestamp-nonce allocation — seq is a millisecond Unix timestamp advanced by max(now_ms, last_nonce + 1). The exchange validates against a sliding window and rejects replays with code 21.
  • Gateway and CometBFT submission — by default, transactions POST to the gateway’s /exchange endpoint; set useGateway: false to broadcast directly to CometBFT’s broadcast_tx_sync.
Beyond trading, the SDK exposes a full query surface: orderbooks, open orders, account balances and positions, market configs, tickers, history, and real-time block events over WebSocket.

​
Available packages

TypeScript / Node.js

npm install @proof/trading-sdk
Pure TypeScript, ESM module. Requires Node.js 18+.

Python

pip install proof-trading-sdk
Backed by a compiled Rust core via PyO3. See python/pyproject.toml.

Rust

proof-trading-sdk = "*"
Native crate at crates/proof-trading-sdk.

​
Devnet defaults

The SDK ships pre-configured for the public Proof devnet. No additional setup is required to start querying.
ParameterDefault
Gateway URLhttps://api.dev.proof.trade
Chain IDexchange-devnet-1
Faucet URLhttps://faucet.dev.proof.trade
Connecting to devnet requires only a chainId: 
import { ExchangeClient } from "@proof/trading-sdk";

const client = new ExchangeClient({ chainId: "exchange-devnet-1" });
const health = await client.queryHealth();
// { status: "ok", height: 123456 }

​
Key capabilities at a glance

Trading actions

Place, cancel, replace, and amend limit orders. Execute market orders, close positions, and submit atomic basket (multi-leg) orders — all via a single discriminated-union Action type.

Full query surface

Query orderbooks, open orders, account info, market configs, tickers, chain status, ADL queues, and withdrawal records without any authentication.

Submission modes

submitTx returns after CheckTx (fire-and-forget with background polling). submitTxCommit polls /tx?hash for up to 9 seconds for synchronous confirmation. Collect all background DeliverTx results with awaitPendingVerifies().

WebSocket events

Subscribe to real-time block events — trades, order placements, position updates, funding, and liquidations — via client.subscribeBlocks() or the raw wss:// feed.

​
Wire format overview

Transactions are MessagePack positional arrays signed over a domain-separated message: 
[2, action_type, seq, payload, pubkey(32B), signature(64B)]
The signature covers DOMAIN_PREFIX(16B) || chain_id(32B) || action_type(1B) || seq(8B BE) || payload. The 32-byte chain_id binding closes the cross-chain replay vector. Full payload layouts are defined in src/types.ts and src/codec.ts.
Prices and quantities are always bigint (u64) — never JavaScript number or floating point. Prices are integer cents (5000000n = 50,000.00)andbalancesaremicroUSDC(‘10000000000n‘=50,000.00) and balances are microUSDC (`10_000_000_000n` = 10,000).

​
Unit conventions

FieldUnitExample
PricesInteger cents5000000n = $50,000.00
Balances / amountsMicroUSDC (6 dp)10_000_000_000n = $10,000
Fees / margin ratesBasis points500 = 5%
Addresses20-byte Uint8ArraypubkeyToOwner(publicKey)

​
Explore further

Quickstart

Generate a keypair, fund via faucet, and place your first limit order in under five minutes.

Installation

TypeScript, Python, and Rust setup with runtime requirements and connectivity tests.

ExchangeClient API

Full reference for all client methods, options, and return types.

Key Management

Ed25519 keypair generation, address derivation, and secure key handling patterns.

Build docs developers (and LLMs) love

Get started for freeTalk to us