# REST API Interaction

The REST API is an essential part of the 21X platform, providing a wide range of functionality to interact with trading pairs, order books, and user-specific data. The API is divided into two categories: **public** and **authenticated** endpoints.

***

## Why Use the REST API?

* **Public Endpoints**\
  Public endpoints are accessible without authentication and are used to:
  * Fetch available trading pairs.
  * Retrieve order book data and price levels.
  * Access general ticker information for trading pairs.
* **Authenticated Endpoints**\
  Authenticated endpoints require user authentication and are designed for private, wallet-specific operations, such as:
  * Viewing orders placed by your wallet.
  * Fetching your order and trade history.
  * Retrieving order IDs (useful for canceling orders).

These endpoints complement the smart contract interactions by providing additional data and ensuring smooth integration for trading activities.

***

## Client Configuration

The 21X SDK includes a REST API client for seamless interaction with the platform. The client supports both synchronous and asynchronous requests, enabling flexible integration into your applications.

### Setting Up the Client

1. **Public Endpoints**\
   Use the `Client` class to interact with public endpoints:

   ```python
   from x21_sdk import Client

   client = Client(base_url="<insert the 21X API url here>")
   ```
2. **Authenticated Endpoints**\
   For endpoints requiring authentication, use the `AuthenticatedClient` class and provide a valid token:

   ```python
   from x21_sdk import AuthenticatedClient

   client = AuthenticatedClient(
        base_url="<insert the 21X API url here>",
        client_id="<insert the client id here>",
        client_secret="<insert the client secret here>",
        token_endpoint="<insert the oidc token endpoint here>",
    )
   ```

Alternatively, you can make use the following environment variables, to auto configure the clients.

```bash
export 21X_BASE_URL=<>
export 21X_AUTH_CLIENT_ID=<>
export 21X_AUTH_CLIENT_SECRET=<>
export 21X_AUTH_CLIENT_TOKEN_ENDPOINT=<>
```

```python
from x21_sdk import Client, AuthenticatedClient

# Initialize either a client for the public endpoints
client = Client()

# Or a Client to use the authenticated endpoints
client = AuthenticatedClient()
```

***

## Example Usage

#### Synchronous Example

Calling an endpoint and working with the response:

```python
from x21_sdk.client.api.public_market_data import get_trading_pairs

# Fetch trading pairs
trading_pairs = get_trading_pairs.sync(client=client)

# Process response
for pair in trading_pairs.items:
    print("orderbook_addr: " + pair.smart_contract_order_book)
    print("base: " + pair.base_token_data.symbol)
    print("quote: " + pair.quote_token_symbol)
```

#### Asynchronous Example

Using the async version of the client:

```python
from x21_sdk.client.api.public_market_data import get_trading_pairs

async def fetch_trading_pairs():
    async with client as client:
        trading_pairs = await get_trading_pairs.asyncio(client=client)
        for pair in trading_pairs.items:
            print("orderbook_addr: " + pair.smart_contract_order_book)
            print("base: " + pair.base_token_data.symbol)
            print("quote: " + pair.quote_token_symbol)

# Run the async function
import asyncio
asyncio.run(fetch_trading_pairs())
```

***

### Advanced Configuration

The client provides options to customize behavior based on your application's needs.

#### SSL Verification

For APIs using HTTPS, SSL verification ensures secure connections. You can specify a custom certificate bundle:

```python
client = Client(
    verify_ssl="/path/to/certificate_bundle.pem",
)
```

To disable SSL verification (not recommended), set `verify_ssl=False`:

```python
client = Client(
    verify_ssl=False,
)
```

#### Customizing HTTPX

You can extend or replace the underlying `httpx` client for advanced use cases:

```python
from x21_sdk import Client

def log_request(request):
    print(f"Request: {request.method} {request.url}")

def log_response(response):
    print(f"Response: {response.status_code} {response.url}")

client = Client(
    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
)
```

For even greater control, set a custom `httpx.Client` instance directly:

```python
import httpx
from x21_sdk import Client

client = Client()
client.set_httpx_client(httpx.Client(base_url="https://api.21x.com", proxies="http://localhost:8030"))
```

***

## Public Endpoints

### `getTradingPairs`

Fetches a list of all available trading pairs on the platform.

#### Parameters

* **None**

#### Example Usage

```python
from x21_sdk.client.api.public_market_data import get_trading_pairs

trading_pairs = get_trading_pairs(client=client)
for pair in trading_pairs.items:
    print(pair)
```

Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure.

***

### `getTradeInfo`

Retrieves trade information for a trading pair

#### Parameters

* **`id` (str)**: The identifier of the trading pair.

#### Example Usage

```python
from x21_sdk.client.api.public_market_data import get_trade_info

id = "06162bc3-9765-4673-a874-9b8a21e97e27"
trade_info = get_trade_info(id, client=client)
print(trade_info)
```

Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure.

***

### `getOrderBookTopOrders`

Retrieves the top orders from the order book for a specified trading pair.

#### Parameters

* **`id` (str)**: The identifier of the trading pair.
* **`kind` (Union\[Unset, OrderKindEnum], optional)**: The type of orders to retrieve (e.g., buy or sell).
* **`max_` (Union\[Unset, int], optional)**: The maximum number of orders to return.

#### Example Usage

```python
from x21_sdk.client.api.public_market_data import get_order_book_top_orders
from x21_sdk.client.models import OrderKindEnum

pair_id = "0xBaseTokenAddress-0xQuoteTokenAddress"
kind = OrderKindEnum.BUY
max_orders = 10

top_orders = get_order_book_top_orders.sync(
    client=client,
    id=pair_id,
    kind=kind,
    max_=max_orders
)

for order in top_orders.buy:
    print(order)
```

#### Notes

* The `kind` parameter can be used to filter results by order type (e.g., only buy or sell orders).
* If `max_` is not provided, the endpoint will return a default number of top orders.

Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure.

***

### `getOrderBookPriceLevels`

Fetches the price levels from the order book for a specified trading pair.

#### Parameters

* **`id` (str)**: The identifier of the trading pair.
* **`kind` (Union\[Unset, OrderKindEnum], optional)**: The type of price levels to retrieve (e.g., buy or sell).
* **`max_` (Union\[Unset, int], optional)**: The maximum number of price levels to return.

#### Example Usage

```python
from x21_sdk.client.api.public_market_data import get_order_book_price_levels
from x21_sdk.client.models import OrderKindEnum

pair_id = "0xBaseTokenAddress-0xQuoteTokenAddress"
kind = OrderKindEnum.SELL
max_levels = 5

price_levels = get_order_book_price_levels.sync(
    client=client,
    id=pair_id,
    kind=kind,
    max_=max_levels
)

for level in price_levels.sell:
    print(level)
```

#### Notes

* The `kind` parameter allows filtering price levels by type (e.g., only buy or sell price levels).
* If `max_` is omitted, the endpoint defaults to returning a predefined number of price levels.

Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure.

***

### `getPostTradeTransparency`

Retrieves regulatory post-trade transparency data for the entire exchange. By default, it shows the most recent trades first. You can limit the results to a specific trading pair by providing its ID.

#### Parameters

* **`query` (Union\[Unset, GetPostTradeTransparencyQuery], optional)**: Query parameters to filter the data, such as trading pair ID.
* **`cursor` (Union\[Unset, str], optional)**: A pagination cursor to navigate through the dataset.
* **`limit` (Union\[Unset, int], optional)**: The maximum number of trades to retrieve.
* **`count` (Union\[Unset, bool], optional)**: If `True`, includes a count of total available trades in the response.

#### Example Usage

```python
from x21_sdk.client.api.public_market_data import get_post_trade_transparency

# Example query to limit data to a specific trading pair
query = {"tradingpair": "06162bc3-9765-4673-a874-9b8a21e97e27"}
limit = 10
cursor = None  # Omit or use a valid cursor for paginated requests

transparency_data = get_post_trade_transparency.sync(
    client=client,
    query=query,
    cursor=cursor,
    limit=limit,
    count=True
)

for trade in transparency_data.items:
    print(trade)
```

#### Notes

* Providing a `trading_pair_id` in the query restricts the results to trades involving that pair.
* Use the `cursor` for paginated requests, especially when dealing with large datasets.
* The `count` parameter helps determine the total number of trades available without fetching all results.
*

Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure.

***

## Authenticated Endpoints

### `getWalletOrders`

#### Description

This authenticated endpoint fetches all orders associated with the specified wallet. By default, it returns open orders. You can filter the results to a specific trading pair or include completed, canceled, and rejected orders by adjusting the parameters.

#### Parameters

* **`wallet_address` (str, required)**: The wallet address to fetch orders for.
* **`query` (Union\[Unset, GetWalletOrdersQuery], optional)**: Filters for the request, such as trading pair ID or status.
* **`cursor` (Union\[Unset, str], optional)**: A pagination cursor to navigate through the dataset.
* **`limit` (Union\[Unset, int], optional)**: The maximum number of orders to retrieve.
* **`count` (Union\[Unset, bool], optional)**: If `True`, includes a count of total available orders in the response.

#### Example Usage

```python
from x21_sdk.client.api.order import get_wallet_orders

# Example query to restrict data to a specific trading pair
query = {"trading_pair": "06162bc3-9765-4673-a874-9b8a21e97e27", "only_open": True}
limit = 10
cursor = None  # Omit or use a valid cursor for paginated requests

wallet_orders = get_wallet_orders.sync(
    client=client,
    wallet_address="0xYourWalletAddress",
    query=query,
    cursor=cursor,
    limit=limit,
    count=True
)

for order in wallet_orders.items:
    print(order)
```

#### Notes

* Set `only_open` to `False` in the query to fetch completed, canceled, and rejected orders instead of open ones.
* Use the `cursor` parameter for paginated requests when dealing with a large number of orders.
* The `count` parameter is helpful for understanding the size of the dataset without fetching all results.

Refer to the [OpenAPI Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structures.

***

### `getWalletTrades`

#### Description

This authenticated endpoint retrieves all completed trades involving the specified wallet. You can optionally restrict the results to a specific trading pair.

#### Parameters

* **`wallet_address` (str, required)**: The wallet address to fetch trades for.
* **`query` (Union\[Unset, GetWalletTradesQuery], optional)**: Filters for the request, such as trading pair ID or trade time range.
* **`cursor` (Union\[Unset, str], optional)**: A pagination cursor to navigate through the dataset.
* **`limit` (Union\[Unset, int], optional)**: The maximum number of trades to retrieve.
* **`count` (Union\[Unset, bool], optional)**: If `True`, includes a count of total available trades in the response.

#### Example Usage

```python
from x21_sdk.client.api.trade import get_wallet_trades

# Example query to fetch trades for a specific trading pair
query = {"trading_pair": "06162bc3-9765-4673-a874-9b8a21e97e27"}
limit = 20
cursor = None  # Use a valid cursor for paginated requests if applicable

wallet_trades = get_wallet_trades.sync(
    client=client,
    wallet_address="0xYourWalletAddress",
    query=query,
    cursor=cursor,
    limit=limit,
    count=True
)

for trade in wallet_trades.items:
    print(trade)
```

#### Notes

* Use the `trading_pair` parameter in the query to restrict results to a specific pair.
* The `cursor` parameter allows for paginated navigation, which is helpful for wallets with a high trade volume.
* Setting the `count` parameter to `True` provides a total count of trades without retrieving the entire dataset.

Refer to the [OpenAPI Documentation](https://docs.21x.eu/api-reference-v1.0) for more details on request/response formats.


---

# Agent Instructions: 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.21x.eu/sdk/03-rest.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.