> For the complete documentation index, see [llms.txt](https://docs.afx.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.afx.xyz/api-reference/quickstart.md).

# Quick Start

{% hint style="info" %}
This guide uses the **Testnet** environment. All operations are free -- use `faucet_claim` to get test funds.
{% endhint %}

## Prerequisites

Two Ethereum wallets are required:

{% columns %}
{% column %}
**Master Wallet**

Controls funds and permissions.

Used to sign `approveAgent` and `withdraw`.
{% endcolumn %}

{% column %}
**Agent Wallet**

Handles day-to-day trading.

Used to sign `placeOrder`, `replaceOrder`, `placeBracketOrder`, `cancelOrder`, `setLeverage`, etc.
{% endcolumn %}
{% endcolumns %}

Store private keys in environment variables. The Python SDK loads keys from the environment and does not accept private keys in public client constructors.

```bash
export AFX_MASTER_PRIVATE_KEY="0xYOUR_MASTER_PRIVATE_KEY"
export AFX_AGENT_PRIVATE_KEY="0xYOUR_AGENT_PRIVATE_KEY"
```

{% hint style="info" %}
On mainnet, the minimum deposit is 10 USDC and the minimum withdrawal is 2 USDC. Testnet examples use faucet funds instead of real deposits.
{% endhint %}

## Install Python SDK

The official Python SDK is maintained in [`afx-dex/afx-python-sdk`](https://github.com/afx-dex/afx-python-sdk). Do not download `dex_client.py`, `dex.proto`, or `dex_pb2.py` from these docs.

```bash
git clone https://github.com/afx-dex/afx-python-sdk.git
cd afx-python-sdk
python3 -m pip install -e .
```

The SDK vendors the generated protobuf module under `afx.protos`, so no manual protobuf compilation is required.

Runnable examples for this flow:

* [faucet\_claim.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/exchange/faucet_claim.py)
* [approve\_agent.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/exchange/approve_agent.py)
* [get\_products.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/info/get_products.py)
* [place\_order.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/exchange/place_order.py)
* [replace\_order.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/exchange/replace_order.py)
* [place\_bracket\_order.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/exchange/place_bracket_order.py)
* [subscribe\_order\_book.py](https://github.com/afx-dex/afx-python-sdk/blob/main/examples/websocket/subscribe_order_book.py)

## First Trade

{% stepper %}
{% step %}
**Initialize the client**

```python
from afx import AfxClient

client = AfxClient.from_env(testnet=True)
```

{% endstep %}

{% step %}
**Claim testnet funds**

Get 500 USDC from the testnet faucet. Signed by the **Master** wallet.

```python
result = client.exchange.faucet_claim()
print(result)  # {"code": 0, "message": "success", ...}
```

{% endstep %}

{% step %}
**Authorize the agent wallet**

The Master wallet grants the Agent wallet permission to trade until the authorization expires.

```python
result = client.exchange.approve_agent(
    agent_name="my-bot",
    validity_seconds=604800,
)
print(result)
```

{% endstep %}

{% step %}
**Query available symbols**

```python
products = client.info.get_products()
for p in products["data"]["perpProducts"][:3]:
    print(f"{p['symbol']} (code: {p['code']}, leverage: {p['maxLeverage']}x)")
```

Use the returned `code` value when placing orders. Do not hardcode product codes or leverage values from examples, because markets and risk parameters can change.
{% endstep %}

{% step %}
**Place a limit order**

Signed by the **Agent** wallet. This places a buy order far below market price so it won't fill immediately.

```python
btc = next(p for p in products["data"]["perpProducts"] if p["symbol"] == "BTCUSDC")

result = client.exchange.place_order(
    symbol_code=int(btc["code"]),
    px="50000.0",      # limit price
    qty="0.001",       # quantity in BTC
    side="BUY",
    ord_type="LIMIT",
    tif="GTC",         # Good Till Cancelled
)
print(f"txHash: {result['data']['txHash']}")
```

{% hint style="success" %}
You've placed your first order! The transaction is submitted to the blockchain and confirmed within seconds.
{% endhint %}
{% endstep %}
{% endstepper %}

## Subscribe to Market Data

Connect to real-time orderbook updates via WebSocket.

```python
import asyncio

async def main():
    message = await client.websocket.subscribe_order_book(
        symbol="BTCUSDC",
        depth=5,
        timeout=10,
    )
    book = message["data"]["book"]
    print(f"Best bid: {book['bids'][0]}, Best ask: {book['asks'][0]}")

asyncio.run(main())
```

## What's Next

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Python SDK</strong></td><td>Install the SDK and run the official examples.</td><td><a href="/pages/gm6l21G4eyGNjnvGjc11">/pages/gm6l21G4eyGNjnvGjc11</a></td></tr><tr><td><strong>Authentication</strong></td><td>How EIP-712 signing works -- Agent vs Master wallet.</td><td><a href="/pages/KD5aN27W1BtKrOW0eFnL">/pages/KD5aN27W1BtKrOW0eFnL</a></td></tr><tr><td><strong>Exchange API</strong></td><td>All trading operations -- orders, leverage, vaults.</td><td><a href="/pages/BuhOTIH4l63pXQfDPXCo">/pages/BuhOTIH4l63pXQfDPXCo</a></td></tr><tr><td><strong>Info API</strong></td><td>Query account, orders, positions, market data.</td><td><a href="/pages/uz7Xewliilx3mtOBwGXU">/pages/uz7Xewliilx3mtOBwGXU</a></td></tr><tr><td><strong>WebSocket</strong></td><td>Real-time orderbook, kline, ticker, and account events.</td><td><a href="/pages/4YkYRib0XiUqm9hKouPx">/pages/4YkYRib0XiUqm9hKouPx</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.afx.xyz/api-reference/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.