PyPSX SDK

API-first trading infrastructure for the Pakistan Stock Exchange.

Installation

pip install pypsx

Try it in a notebook

One-liners — no client to construct

import pypsx

df = pypsx.download("OGDC", period="1y")
result = pypsx.backtest("dual_sma_momentum", "OGDC", period="1y", initial_cash=1_000_000)
quote = pypsx.get_quote("OGDC")
depth = pypsx.get_market_depth("OGDC")

These read PYPSX_API_KEY_ID/PYPSX_API_SECRET_KEY from the environment automatically. For order placement, positions, and account state, use TradingClient below.

Quick Start

Start with paper trading. It is the safety-first way to test your strategy, validate your order flow, and watch your dashboard update in real time before risking real capital.

import os
from dotenv import load_dotenv
from pypsx import TradingClient

load_dotenv()

client = TradingClient(
    api_key=os.getenv("PYPSX_API_KEY_ID"),
    secret_key=os.getenv("PYPSX_API_SECRET_KEY"),
    paper=True,
)

account = client.get_account()
print(f"Connected! Current Balance: PKR {account.cash}")

order = client.place_manual_order(
    symbol="OGDC",
    side="BUY",
    quantity=10,
    order_type="MARKET",
)

print("Submitted:", order["order_id"], order["status"])

You can also load keys directly from environment variables:

from pypsx import TradingClient

client = TradingClient.from_env(paper=True)

Your First Trade

Step 1: Generate a paper key in the PyPSX dashboard.
Step 2: Copy the script above into my_bot.py.
Step 3: Set your own PYPSX_API_KEY_ID and PYPSX_API_SECRET_KEY in .env.
Step 4: Run python my_bot.py while the market is open.
Step 5: Watch orders, fills, and positions appear in the dashboard automatically.

The Power of PyPSX

PyPSX gives algorithmic traders a clean Python interface for the Pakistan Stock Exchange without exposing them to exchange plumbing.

Paper Trading

PyPSX currently operates in paper trading mode: simulated orders, no real money.

Real-Time Trading Experience

With PyPSX you can:

• Read positions, orders, and account state from Python
• Submit orders with a simple REST interface
• See fills reflected in the web dashboard without manual refresh
• Build bots around trading logic instead of exchange protocol handling

Developer's Promise

PyPSX handles the operational complexity of PSX integration, including request authentication, endpoint routing, and exchange connectivity. You focus on signal generation, risk rules, and execution logic. We handle the FIX-side complexity behind the API.

Authentication

How To Get Your Keys

1. Sign in to the PyPSX dashboard.
2. Open Settings.
3. Select the account you want to trade.
4. Click Generate Paper Key or Generate Live Key.
5. Copy the Public Key ID and Secret Key.

How The SDK Uses Them

Use the credentials directly in TradingClient(...):

from pypsx import TradingClient

client = TradingClient(
    api_key=os.getenv("PYPSX_API_KEY_ID"),
    secret_key=os.getenv("PYPSX_API_SECRET_KEY"),
    paper=True,
)

Under the hood, the SDK automatically sends:

PYPSX-API-KEY-ID: <your-public-key-id>
PYPSX-API-SECRET-KEY: <your-secret-key>

If you are building against the API without the Python SDK, send those same headers yourself.

API Reference

Examples

Paper Trading

import os
from pypsx import TradingClient

client = TradingClient(
    api_key=os.getenv("PYPSX_API_KEY_ID"),
    secret_key=os.getenv("PYPSX_API_SECRET_KEY"),
    paper=True,
)

valuation = client.get_portfolio_valuation()
positions = client.get_positions()
orders = client.get_orders(limit=25)

print("Equity:", valuation["equity"])
print("Positions:", len(positions))
print("Orders:", len(orders))

Simple Bot Pattern

from pypsx import TradingClient

SYMBOL = "OGDC"

client = TradingClient(
    api_key="PK_xxxxxxxxxxxx",
    secret_key="your_secret_key",
    paper=True,
)

positions = client.get_positions()
already_holding = any(
    position["symbol"] == SYMBOL and float(position["qty"]) > 0
    for position in positions
)

if not already_holding:
    client.place_manual_order(
        symbol=SYMBOL,
        side="BUY",
        quantity=10,
        order_type="MARKET",
    )

Best Practices

• Use .env files or a secrets manager for credentials. Do not hardcode production keys into source control.
• Start every new strategy with paper=True.
• Treat paper trading as your pre-flight checklist before switching to live.
• Run execution scripts when the market is open so fills, liquidity, and dashboard feedback reflect real conditions.
• Add explicit guards in your code for position sizing, duplicate orders, and risk limits.
• Close clients cleanly with client.close() in longer-running scripts or services.

Raw HTTP Example

If you are not using the SDK, this is the equivalent request format:

curl -X POST "$PYPSX_API_BASE_URL/orders" \
  -H "Content-Type: application/json" \
  -H "PYPSX-API-KEY-ID: $PYPSX_API_KEY_ID" \
  -H "PYPSX-API-SECRET-KEY: $PYPSX_API_SECRET_KEY" \
  -d "{\"symbol\":\"OGDC\",\"side\":\"BUY\",\"quantity\":10,\"order_type\":\"MARKET\",\"mode\":\"PAPER\",\"commission_rate\":0.02}"

Set commission_rate only when you want to override the default fee behavior for a specific order. The value is a percentage, so 0.02 means 0.02%.

Additional Examples

• examples/pypsx_client_example.py
• examples/example_bot.py