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

# A Note for Python Devs

> Python developers are able to interact with Whirlpool through Whirlpool Essential library!

# A Note for Python Devs

Python developers are able to interact with Whirlpool through Whirlpool Essential library!

<Card title="🔗 Whirlpool Essentials" icon="github" href="https://pypi.org/project/whirlpool-essentials/">
  [https://pypi.org/project/whirlpool-essentials/](https://pypi.org/project/whirlpool-essentials/)
</Card>

<Card title="🔗 Whirlpool Essentials - GitHub" icon="github" href="https://github.com/everlastingsong/whirlpool-essentials">
  [https://github.com/everlastingsong/whirlpool-essentials](https://github.com/everlastingsong/whirlpool-essentials)
</Card>

Whirlpool Essentials library contains almost functions provided by SDK for Typescript.

From the following code, you will find many common codes.

```python theme={"system"}
import asyncio

from solana.rpc.async_api import AsyncClient
from solders.pubkey import Pubkey
from solders.keypair import Keypair

from orca_whirlpool.constants import ORCA_WHIRLPOOL_PROGRAM_ID
from orca_whirlpool.context import WhirlpoolContext
from orca_whirlpool.utils import PriceMath, DecimalUtil

SOL_USDC_8_WHIRLPOOL_PUBKEY = Pubkey.from_string("7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm")

async def main():
    connection = AsyncClient(RPC_ENDPOINT_URL)
    ctx = WhirlpoolContext(ORCA_WHIRLPOOL_PROGRAM_ID, connection, Keypair())

    # get SOL/USDC(ts=8) whirlpool
    whirlpool_pubkey = SOL_USDC_8_WHIRLPOOL_PUBKEY
    whirlpool = await ctx.fetcher.get_whirlpool(whirlpool_pubkey)
    decimals_a = (await ctx.fetcher.get_token_mint(whirlpool.token_mint_a)).decimals  # SOL_DECIMAL
    decimals_b = (await ctx.fetcher.get_token_mint(whirlpool.token_mint_b)).decimals  # USDC_DECIMAL

    print("whirlpool token_mint_a", whirlpool.token_mint_a)
    print("whirlpool token_mint_b", whirlpool.token_mint_b)
    print("whirlpool tick_spacing", whirlpool.tick_spacing)
    print("whirlpool tick_current_index", whirlpool.tick_current_index)
    print("whirlpool sqrt_price", whirlpool.sqrt_price)
    price = PriceMath.sqrt_price_x64_to_price(whirlpool.sqrt_price, decimals_a, decimals_b)
    print("whirlpool price", DecimalUtil.to_fixed(price, decimals_b))

asyncio.run(main())
```

For more examples including position management and swaps, see the [Whirlpool Essentials GitHub repository](https://github.com/everlastingsong/whirlpool-essentials).

***

## Orca REST API

The public REST API provides pool, token, and protocol data without requiring a wallet or on-chain connection. Base URL: `https://api.orca.so/v2/solana`

Install the `requests` library if you don't already have it:

```bash theme={"system"}
pip install requests
```

### Get protocol stats

```python theme={"system"}
import requests

response = requests.get("https://api.orca.so/v2/solana/protocol")
data = response.json()
print(data)
```

### Search for pools by token pair

```python theme={"system"}
import requests

response = requests.get(
    "https://api.orca.so/v2/solana/pools/search",
    params={"q": "SOL-USDC"}
)
pools = response.json()
for pool in pools.get("data", []):
    print(pool)
```

### Look up a token

```python theme={"system"}
import requests

response = requests.get(
    "https://api.orca.so/v2/solana/tokens/search",
    params={"q": "ORCA"}
)
tokens = response.json()
print(tokens)
```

Full API reference and interactive explorer: [api.orca.so/docs](https://api.orca.so/docs)

***

## Using Orca in AI Agent Pipelines

Both approaches above are straightforward to wrap as tools in Python-based agent frameworks.

**Pattern for a read-only pool monitoring tool:**

* Use the REST API to fetch pool data (no wallet, no async complexity)
* Parse the JSON response and return structured data to your agent
* Use this to drive decisions: is APY above threshold? Is the price in a target range?

**Pattern for an execution tool:**

* Use `whirlpool-essentials` for on-chain reads and transaction building
* Load a wallet from a keypair file (keep it isolated from production funds)
* Execute swaps or position operations in response to agent decisions

<Warning>
  Never expose private keys in agent prompts, logs, or environment variables visible to external services. Use a dedicated, isolated keypair for any automated agent.
</Warning>