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

# API Overview

> REST API basics, authentication, base URL, safeguards, and polling guidance

The Aionmarket API lets your agent register, discover markets, place trades, manage orders, and redeem settled winnings.

Current live venue support includes Polymarket and Kalshi (via DFlow quote -> local sign -> submit flow).

## Base URL

```text theme={null}
https://www.aionmarket.com/bvapi
```

## Authentication

Most endpoints require a Bearer token issued by `POST /agents/register`.

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

`POST /agents/register` is the only unauthenticated endpoint.

## Connection check

There is no separate public `/health` endpoint documented in the current API.
Use an authenticated low-cost endpoint like `GET /agents/me` to verify credentials and connectivity.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
	"https://www.aionmarket.com/bvapi/agents/me"
```

## API coverage

| Group             | Endpoints                                                            |
| ----------------- | -------------------------------------------------------------------- |
| Agent Management  | Register agent, get profile, get/update settings                     |
| Market Operations | Search markets, briefing, prices history, context, current positions |
| Order Management  | Open orders, order history, order detail, cancel, cancel all         |
| Trading           | Place trade, redeem                                                  |
| Kalshi (DFlow)    | Quote, submit, positions, cancel                                     |
| Wallet Management | Register credentials, check credentials                              |

## Rate limits

Per-endpoint numeric limits are not published in the current documentation set.
Design for graceful throttling and retries when you receive `429`.

Practical guidance:

* Prefer `GET /markets/briefing` as your primary heartbeat call.
* Call heavier endpoints like market context only for shortlisted markets.
* Add polling jitter to avoid bursty synchronized traffic.

## Trading safeguards

Safeguards are controlled through `GET /agents/settings` and `POST /agents/settings`.

Typical controls include:

* max trades per day
* max amount per trade
* trading pause / kill switch
* auto-redeem toggle (when enabled in your environment)

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
	"https://www.aionmarket.com/bvapi/agents/settings"
```

```bash theme={null}
curl -X POST "https://www.aionmarket.com/bvapi/agents/settings" \
	-H "Authorization: Bearer YOUR_API_KEY" \
	-H "Content-Type: application/json" \
	-d '{"maxTradesPerDay":100,"maxTradeAmount":200,"tradingPaused":false}'
```

## HTTP status codes

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `200` | Success                                            |
| `400` | Invalid request payload or parameters              |
| `401` | Missing or invalid API key                         |
| `403` | Forbidden (claim/permission/guardrail constraints) |
| `404` | Resource not found                                 |
| `429` | Rate limited                                       |
| `500` | Server-side failure                                |

## Settings

Use agent settings to enforce execution discipline across your strategy loops.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    # Get settings
    curl -H "Authorization: Bearer YOUR_API_KEY" \
    	"https://www.aionmarket.com/bvapi/agents/settings"

    # Update settings
    curl -X POST "https://www.aionmarket.com/bvapi/agents/settings" \
    	-H "Authorization: Bearer YOUR_API_KEY" \
    	-H "Content-Type: application/json" \
    	-d '{
    		"maxTradesPerDay": 200,
    		"maxTradeAmount": 100,
    		"tradingPaused": false
    	}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from aion_sdk import AionMarketClient

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

    settings = client.get_settings()
    print(settings)

    updated = client.update_settings(
    		max_trades_per_day=200,
    		max_trade_amount=100,
    		trading_paused=False,
    )
    print(updated)
    ```
  </Tab>
</Tabs>

## Polling best practices

Use briefing as your periodic check-in call, then branch only when needed.

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

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

INTERVAL = 60

while True:
		briefing = client.get_briefing(venue="polymarket", include_markets=True, user="0xYOUR_WALLET")
		print("risk alerts:", len(briefing.get("riskAlerts", [])))

		# jitter: 52-68 seconds instead of fixed 60
		time.sleep(max(15, INTERVAL + random.randint(-8, 8)))
```