Python Integration

This guide covers how to integrate with 01 Exchange using Python and the protobuf-based API.

[!NOTE] Unlike the TypeScript SDK, Python integration uses the raw REST API with protobuf encoding. This approach gives you full control but requires more low-level setup.

Prerequisites

Python 3.8+
protobuf for message encoding
cryptography for Ed25519 signing
requests for HTTP calls
base58 for key encoding

Installation


pip install protobuf cryptography requests base58

Or with uv:


uv add protobuf cryptography requests base58

Generate Protocol Buffers

Download and compile the protobuf schema:


# Download schema
curl https://zo-devnet.n1.xyz/schema.proto -o schema.proto
 
# Generate Python bindings
protoc --python_out=. schema.proto

This creates schema_pb2.py which provides all message types (Action, Receipt, etc.).

Project Structure


your-project/
├── schema.proto        # Downloaded schema
├── schema_pb2.py       # Generated Python bindings
├── id.json             # Your Solana keypair (32-byte array)
└── main.py             # Your trading script

Basic Setup


import json
import requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from base58 import b58encode
 
import schema_pb2
 
API_URL = "https://zo-devnet.n1.xyz"  # or "https://zo-mainnet.n1.xyz"
 
# Load your Solana keypair
with open("id.json", "r") as f:
    key_data = json.load(f)
 
# Create signing key from first 32 bytes
user_signkey = Ed25519PrivateKey.from_private_bytes(bytes(key_data[:32]))
user_pubkey = user_signkey.public_key().public_bytes_raw()
 
print(f"User pubkey: {b58encode(user_pubkey).decode()}")

Key Concepts

Keypairs

You need two types of keys:

Key Type	Purpose	Signing Method
User Key	Your Solana wallet key	Signs `CreateSession` (hex-encoded)
Session Key	Temporary trading key	Signs all other actions (raw bytes)

Actions and Receipts

All trading operations follow this pattern:

Create an Action protobuf message
Serialize and sign it
POST to /action endpoint
Parse the Receipt response

Server Timestamp

Always fetch the server timestamp for action construction:


def get_server_timestamp():
    resp = requests.get(f"{API_URL}/timestamp")
    return int(resp.json())

Next Steps

Session & Authentication - Create a trading session
Trading Operations - Place and cancel orders
Market Data - Fetch market information