Metadata-Version: 2.4
Name: vordium
Version: 1.1.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.

## Roll B: the signing switch and agent names

The chain changes its signing formats once, at an activation height `H` it publishes in `releases.json`
(`aa2007_activation_height`). Below `H` it accepts only the legacy formats, from `H` only the new ones. The SDK reads
`H`, the genesis and the current height live, and refuses to sign in the 3,000 heights before `H`:

```python
from vordium import read_signing_phase, registration, rename, sign_owner_op

phase = read_signing_phase()          # read it right before signing: legacy / window / genesis-bound / unknown
op, value = registration(owner, agent, "strategy: Grid", expires_ms, nonce, phase, name="Grid bot")
body = sign_owner_op(owner_key, op, value)   # RegisterAgent below H; RegisterAgentV2 (name required) from H
```

Agent names follow the chain's rule: 3–32 ASCII characters (`A-Z a-z 0-9 space - _ .`), no reserved words such as
"vordium" or "admin"; `prepare_name()` normalises and checks one, and `agent_display_name()` renders
`<name> · 0xAbCd…1234`.

### Agent policies (from `H`)

An owner sets what an agent may do with `SetAgentPolicyV1`, and clears a risk lock with `ClearAgentLock`. The chain
drops a policy it refuses without saying so, so the SDK checks the stateless rules first:

```python
from vordium import PolicyV1, set_policy, clear_lock, sign_owner_op, policy_problems

op, value = set_policy(owner, agent, policy, nonce, phase, now_ms)     # raises, naming every reason, if the chain would drop it
body = sign_owner_op(owner_key, op, value)
op, value = clear_lock(owner, agent, lock_since_ms, nonce, phase)     # clears only the lock that began at lock_since_ms
```

An agent may tighten its own policy (never loosen it) with `set_policy(..., stored=current, signer="agent")` and
`sign_agent_policy(agent_key, value)`.

### Pool and staking

Deposits, withdrawals, staking, unstaking and claims are messages the OWNER signs; a session key is refused on all of
them except a claim:

```python
from vordium import sign_money_op
from vordium.money import to_units

body = sign_money_op(owner_key, "VlpDeposit", {"user": owner, "amount_6dec": to_units("25", 6), "nonce": nonce},
                     chain_id, phase)     # POST it to /vlp/deposit
```

## 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).
