sora2API

SORA v2 API Wrapper — Python interface for the SORA decentralized economy platform, providing balance queries, token swaps via Polkaswap DEX, liquidity pool inspection, and network status monitoring

SORA v2 API Wrapper

Python interface for the SORA v2 decentralized economy platform — balance queries, token swaps, liquidity pools, and network monitoring.

Features · Getting Started · Configuration · Architecture

---

Overview

SORA v2 is a decentralized economic system built on Substrate, featuring:

• Polkaswap DEX — a non-custodial decentralized exchange with multiple liquidity sources (XYK pools, multi-collateral bonding curve, order book)
• XOR — the native utility and governance token with a token bonding curve supply mechanism
• VAL — validator reward token for SORA network validators
• PSWAP — liquidity provision incentive token

This wrapper provides a Python API client and interactive TUI for querying balances, executing swaps, inspecting liquidity pools, and monitoring network state.

---

Features

Feature	Description
Balance queries	Fetch asset balances for any SORA account
Token swaps	Get quotes and execute swaps via Polkaswap DEX
Liquidity pools	List pools with reserve and liquidity data
Network info	Chain metadata, block height, peer count
Well-known assets	Built-in resolution for XOR, VAL, PSWAP, DAI, ETH, XSTUSD
Multi-source routing	XYK Pool and bonding curve routing support
Data models	Typed dataclasses for assets, pools, quotes, results
Rich TUI	Interactive terminal menu for all operations
Configurable	JSON config with interactive setup wizard

---

Getting Started

Prerequisites

• Python 3.9+
• Network access to a SORA node or API endpoint

Installation

git clone https://github.com/example/sora2api-wrapper.git
cd sora2api-wrapper

pip install -r requirements.txt

python main.py

Quick Setup

1. Run python main.py and select Install dependencies
2. Select Configure API to set endpoint URLs
3. Use Query balances to check account holdings
4. Use Swap tokens to get quotes and execute trades
5. Use Liquidity pools to browse available pools

---

Configuration

Configuration is stored in config.json. Edit directly or use the interactive setup.

Parameter	Default	Description
api_url	https://mof.sora.org	SORA REST API base URL
substrate_url	wss://mof2.sora.org	Substrate WebSocket endpoint
network	mainnet	Network (mainnet or testnet)
default_dex_id	0	Default DEX ID for Polkaswap
timeout	30	Request timeout in seconds

---

Architecture

sora2api/
├── main.py              # TUI entry point (Rich-based menu)
├── client.py            # SORA API client (balances, swaps, pools, network)
├── config.py            # Configuration load/save/interactive setup
├── models.py            # Data models (Asset, Pool, SwapQuote, SwapResult, etc.)
├── config.json          # Runtime configuration
├── requirements.txt     # Python dependencies
└── README.md

API Client

The SoraClient class handles all communication with the SORA network API:

• Balance queries via /accounts/{address}/balances
• Swap quotes via /dex/quote with configurable liquidity sources
• Swap execution via /dex/swap with slippage tolerance
• Pool listing via /dex/pools
• Network info via /network/info

Data Models

All API responses are mapped to typed Python dataclasses:

• Asset — registered token with ID, symbol, precision
• Pool — liquidity pool with reserves and fee data
• SwapQuote — price quote with route and impact information
• SwapResult — executed swap with transaction hash and status
• AccountBalance — per-asset balance breakdown (free, reserved, frozen)
• NetworkInfo — chain state snapshot

---

Well-Known Assets

Symbol	Description
XOR	Native utility token, bonding curve supply
VAL	Validator reward token
PSWAP	Polkaswap liquidity incentive token
DAI	Bridged MakerDAO stablecoin
ETH	Bridged Ether
XSTUSD	SORA synthetic USD stablecoin

---

Dependencies

Package	Purpose
rich	Terminal UI, tables, panels, prompts
requests	HTTP client for REST API calls
websockets	WebSocket connection to Substrate nodes
substrate-interface	Substrate RPC and storage queries

---

Disclaimer

This tool is provided for informational and development purposes. Always verify swap parameters and slippage settings before executing trades. The authors accept no responsibility for financial losses from incorrect usage or API changes.

---

MIT License · Contributions welcome