> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aionmarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install, initialize, and use the aion-sdk Python package

Install, initialize, and use the `aion-sdk` Python package.

The `aion-sdk` package wraps [the REST API with an authenticated client](/api-reference/introduction) for agent management, market discovery, wallet credential setup, trading, order management, and redemption.

All SDK methods map closely to REST endpoints in the API Reference.

SDK source code:

* `https://github.com/aionmarket/aion-sdk`

The current SDK focuses on:

* Agent registration and authentication
* Market search, briefing, and context lookup
* Wallet credential registration and validation
* Trading, order inspection, cancellation, and redemption

<Tip>
  The SDK requires your API key and automatically sends `Authorization: Bearer
      YOUR_API_KEY` on every authenticated request. If `api_key` is missing or
  invalid, requests fail with `401`.
</Tip>

## Installation

Install from PyPI:

```bash theme={null}
pip install aion-sdk
```

Install from source:

```bash theme={null}
git clone https://github.com/aionmarket/aion-sdk.git
cd aion-sdk
pip install -e .
```

## Initialization

Use environment variables (recommended):

```bash theme={null}
export AIONMARKET_API_KEY="YOUR_API_KEY"
export AIONMARKET_BASE_URL="https://www.aionmarket.com/bvapi"  # optional override
```

Initialize from environment:

```python theme={null}
from aion_sdk import AionMarketClient

client = AionMarketClient()
```

Pass API key directly:

```python theme={null}
from aion_sdk import AionMarketClient

client = AionMarketClient(api_key="YOUR_API_KEY")
```

Pass API key plus explicit base URL:

```python theme={null}
from aion_sdk import AionMarketClient

client = AionMarketClient(
    api_key="YOUR_API_KEY",
    base_url="https://www.aionmarket.com/bvapi",
)
```

## Quick example

Find markets, check context, and prepare trade execution:

```python theme={null}
from aion_sdk import AionMarketClient

client = AionMarketClient(
    api_key="YOUR_API_KEY",
    base_url="https://www.aionmarket.com/bvapi",
)

wallet = "0xYOUR_WALLET"
markets = client.get_markets(q="bitcoin", limit=5, venue="polymarket")

if markets:
    market_id = markets[0]["id"]
    context = client.get_market_context(
        market_id=market_id,
        venue="polymarket",
        user=wallet,
        my_probability=0.62,
    )

    print("market:", markets[0].get("title"))
    print("warnings:", context.get("warnings", []))

    # Build a real EIP712 signed order payload before calling client.trade(...)
```

For full order execution flow, see `/essentials/trading-guide`.

## Data classes

The SDK currently returns Python dictionaries/lists with type hints (not runtime dataclass objects).

### Market

Typical market fields:

```python theme={null}
market["id"]
market["title"]
market["question"]
market["category"]
market["bestBid"]
market["bestAsk"]
market["volume24hr"]
market["active"]
```

### Trade Result

Typical trade response fields:

```python theme={null}
result["success"]
result["orderId"]
result["status"]
result["walletAddress"]
result["signatureType"]
```

### Position

Position fields from `GET /markets/current-positions` depend on backend response shape. Typical fields include market ID, side/outcome, size, pricing, and PnL-related values.

## Environment Variables

| Variable              | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `AIONMARKET_API_KEY`  | Agent API key                                         |
| `AIONMARKET_BASE_URL` | Optional API base URL override for sandbox or staging |

## Supported Methods

### Agent Management

* `register_agent()`
* `claim_preview()`
* `get_me()`
* `get_settings()`
* `update_settings()`
* `get_skills()`

### Market Operations

* `get_markets()`
* `get_market()`
* `check_market_exists()`
* `get_prices_history()`
* `get_briefing()`
* `get_market_context()`

### Wallet Management

* `check_wallet_credentials()`
* `register_wallet_credentials()`

### Trading Operations

* `trade()`
* `get_open_orders()`
* `get_order_history()`
* `get_order_detail()`
* `cancel_order()`
* `cancel_all_orders()`
* `redeem()`

## Error Handling

```python theme={null}
from aion_sdk import AionMarketClient, ApiError

client = AionMarketClient(api_key="YOUR_API_KEY", base_url="https://www.aionmarket.com/bvapi")

try:
    result = client.get_me()
    print(result)
except ApiError as e:
    print(f"API error: {e.message}")
    print(f"status_code: {e.status_code}")
    print(f"code: {e.code}")
```

Common failure patterns:

* `401`: invalid/missing API key (Authorization header issue)
* `400`: payload or parameter mismatch
* `429`: rate limit
* `500`: server-side error

## Next Steps

* Read `/essentials/trading-guide` for the full end-to-end flow.
* Read `/essentials/wallet-setup` before live order submission.
* Read `/api-reference/introduction` for API-wide behavior.