Metadata-Version: 2.4
Name: vordium
Version: 1.0.0
Summary: Python SDK for AI agents on Vordium Chain — The AI Layer
Author-email: Vordium <dev@vordium.com>
License: MIT
Project-URL: Homepage, https://vordium.com
Project-URL: Documentation, https://docs.vordium.com
Project-URL: Repository, https://github.com/Vordium/vordium-sdk
Project-URL: Explorer, https://vordscan.io
Keywords: vordium,blockchain,ai,agents,web3,evm,crypto,perps,clob
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: web3>=6.0.0
Requires-Dist: eth-account>=0.9.0
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# Vordium Python SDK

The AI Layer for crypto. `vordium` is the Python SDK for building AI agents that
read and trade on **Vordium Chain** — an EVM L1 whose perp DEX (Vordex) is a
central limit order book settled in consensus, chainId **101101**.

```bash
pip install vordium
```

## Why this SDK is safe to point at a live chain

- **The network is discovered, never hardcoded.** chainId, RPC, explorer and the
  Arbitrum bridge are resolved at runtime from the canonical spec and the node's
  `/status`. Nothing is baked in, so a relaunch/wipe can't leave you signing
  against a stale chain.
- **The signing chainId is resolved by agreement.** `eth_chainId`, the spec, and
  any pin you set must all agree, or the SDK refuses to sign — a mismatched
  signing domain would otherwise yield a valid signature on the wrong chain.
- **EIP-712 domains are genesis-bound.** The VordCore domain salt is derived from
  the live `genesis_sha256`; if the node can't tell the SDK its genesis, the SDK
  refuses to sign rather than emit a digest the chain will reject.

## Quick start (read-only)

```python
from vordium import Vordex

dex = Vordex()
for m in dex.markets():                 # live perp markets (ETH, BTC, …)
    print(m["symbol"], m["mark_price"])

book = dex.orderbook(1)                  # resting bids/asks for pair 1
print(dex.mark_price(1))                 # human mark price
```

## Agents

An agent on Vordium is an owner account operated through a **session key** bounded
by owner-set, opt-in, on-chain caps. A session key can only ever do what the
native agent gate allows; it can never withdraw funds or change its own caps.

```python
import os
from vordium import Agent, Vordex

agent = Agent(os.environ["VORDIUM_PRIVATE_KEY"])   # never hardcode a key
print(agent.address, agent.balance)                # native VORD (authoritative /vord route)

dex = Vordex()
print(dex.balance(agent.address))                  # USDC collateral
print(dex.positions(agent.address))                # open perp positions
```

Order placement is EIP-712 signed with the session key. Agent write ops are inert
until the owner enables agent trading on-chain — reads work regardless, and calls
that aren't live yet return an "unavailable" result rather than inventing data.

## CLI

```bash
vordium init         # scaffold a config
vordium balance 0x…  # read a native VORD balance
```

## Units (do not mix)

| context            | price          | size           |
|--------------------|----------------|----------------|
| signed order (EIP-712 / POST) | uint64, 8 decimals | uint128, 18 decimals |
| read endpoints (`/oracle/*`)  | 1e6 integers / floats | — |

## Links

- RPC: https://rpc.vordium.com
- Docs: https://docs.vordium.com
- Explorer: https://vordscan.io
- Source: https://github.com/Vordium/vordium-sdk

## License

MIT

## Genesis-bound EIP-712 domains (mainnet genesis `2c1c0679…`)
Every Vordium signing domain binds its `salt` to the chain's genesis sha256, so a signature for one
relaunch of chainId 101101 never verifies on another. `vordium.domains` derives all four from the
live node (`/status.genesis_sha256`) and never pins them; at the current mainnet genesis they are:
VordCore `0x68b86fee…`, VordexSession `0x519818aa…`, OwnerOp `0x496cb26f…`, InfraOp `0xc9b62487…`
(`vordium.domains.verify_against_node()` re-derives and compares at runtime).
