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

# Best Practices

> Recommended patterns for using the SDK.

Follow these patterns for reliable, performant SDK usage.

***

## SDK Initialization

Initialize the SDK once and reuse it:

> [tab] TypeScript
>
> ```typescript theme={"dark"}
> // ✓ Good - single instance
> let sdk: OricaSDK | null = null;
>
> async function getSDK(): Promise<OricaSDK> {
>   if (!sdk) {
>     const connection = new Connection("https://api.mainnet-beta.solana.com");
>     sdk = await OricaSDK.createFromChain(connection);
>   }
>   return sdk;
> }
>
> // ✗ Bad - creating new instance each time
> async function badExample() {
>   const sdk = await OricaSDK.createFromChain(connection);
>   return sdk.orica.fetchAllMarkets();
> }
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # ✓ Good - single instance
> _sdk: OricaSDK | None = None
>
> async def get_sdk() -> OricaSDK:
>     global _sdk
>     if _sdk is None:
>         connection = AsyncClient("https://api.mainnet-beta.solana.com")
>         _sdk = await OricaSDK.create(connection)
>     return _sdk
>
> # ✗ Bad - creating new instance each time
> async def bad_example():
>     sdk = await OricaSDK.create(connection)
>     return await sdk.orica.fetch_all_markets()
> ```

***

## Connection Management

Use a reliable RPC provider and appropriate commitment:

> [tab] TypeScript
>
> ```typescript theme={"dark"}
> // Production: use dedicated RPC with confirmed commitment
> const connection = new Connection(
>   "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
>   { commitment: "confirmed" }
> );
>
> // For time-sensitive reads
> const recentMarket = await sdk.orica.fetchMarket(address);
>
> // For guaranteed finality (slower)
> const connection = new Connection(url, { commitment: "finalized" });
> ```

> [tab] Python
>
> ```python theme={"dark"}
> from solana.rpc.commitment import Confirmed, Finalized
>
> # Production: use dedicated RPC with confirmed commitment
> connection = AsyncClient(
>     "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
>     commitment=Confirmed
> )
>
> # For guaranteed finality (slower)
> connection = AsyncClient(url, commitment=Finalized)
> ```

***

## Batching Requests

Reduce RPC calls by batching:

> [tab] TypeScript
>
> ```typescript theme={"dark"}
> // ✓ Good - single call
> const markets = await sdk.orica.fetchAllMarkets();
>
> // ✗ Bad - N calls
> const marketAddresses = [...];
> for (const addr of marketAddresses) {
>   await sdk.orica.fetchMarket(addr); // N calls
> }
>
> // ✓ Better - parallel if you need specific markets
> const markets = await Promise.all(
>   marketAddresses.map(addr => sdk.orica.fetchMarket(addr))
> );
> ```

> [tab] Python
>
> ```python theme={"dark"}
> import asyncio
>
> # ✓ Good - single call
> markets = await sdk.orica.fetch_all_markets()
>
> # ✗ Bad - N sequential calls
> market_addresses = [...]
> for addr in market_addresses:
>     await sdk.orica.fetch_market(addr)  # N calls
>
> # ✓ Better - parallel if you need specific markets
> markets = await asyncio.gather(*[
>     sdk.orica.fetch_market(addr) for addr in market_addresses
> ])
> ```

***

## Transaction Building

Combine multiple instructions efficiently:

> [tab] TypeScript
>
> ```typescript theme={"dark"}
> import { Transaction } from "@solana/web3.js";
>
> // Build all instructions
> const buyIxs = await sdk.orica.buildBuy(...);
> const sellIxs = await sdk.orica.buildSell(...);
>
> // Combine into single transaction (if they fit)
> const tx = new Transaction()
>   .add(...buyIxs)
>   .add(...sellIxs);
>
> // Single signature required
> await sendAndConfirmTransaction(connection, tx, [wallet]);
> ```

> [tab] Python
>
> ```python theme={"dark"}
> from solana.transaction import Transaction
>
> # Build all instructions
> buy_ixs = await sdk.orica.build_buy(...)
> sell_ixs = await sdk.orica.build_sell(...)
>
> # Combine into single transaction (if they fit)
> tx = Transaction()
> tx.add(*buy_ixs)
> tx.add(*sell_ixs)
>
> # Single signature required
> await connection.send_transaction(tx, wallet)
> ```

***

## Caching

Cache data that doesn't change frequently:

> [tab] TypeScript
>
> ```typescript theme={"dark"}
> // Global state rarely changes - cache it
> let cachedGlobalState: GlobalState | null = null;
> let lastFetch = 0;
> const CACHE_TTL = 60_000; // 1 minute
>
> async function getGlobalState(): Promise<GlobalState> {
>   const now = Date.now();
>   if (!cachedGlobalState || now - lastFetch > CACHE_TTL) {
>     cachedGlobalState = await sdk.orica.fetchGlobalState();
>     lastFetch = now;
>   }
>   return cachedGlobalState;
> }
> ```

> [tab] Python
>
> ```python theme={"dark"}
> import time
>
> # Global state rarely changes - cache it
> _cached_global_state: GlobalState | None = None
> _last_fetch = 0
> CACHE_TTL = 60  # 1 minute
>
> async def get_global_state() -> GlobalState:
>     global _cached_global_state, _last_fetch
>     now = time.time()
>     if _cached_global_state is None or now - _last_fetch > CACHE_TTL:
>         _cached_global_state = await sdk.orica.fetch_global_state()
>         _last_fetch = now
>     return _cached_global_state
> ```

***

## Pre-flight Checks

Validate before submitting transactions:

> [tab] TypeScript
>
> ```typescript theme={"dark"}
> async function safeBuy(market: PublicKey, amount: BN, outcome: number) {
>   // 1. Check market status
>   const marketData = await sdk.orica.fetchMarket(market);
>   if (marketData.status !== "open") {
>     throw new Error("Market is not open for trading");
>   }
>
>   // 2. Check close time
>   const now = Math.floor(Date.now() / 1000);
>   if (marketData.closeTime.toNumber() < now) {
>     throw new Error("Market has closed");
>   }
>
>   // 3. Check outcome is valid
>   if (outcome >= marketData.outcomeCount) {
>     throw new Error("Invalid outcome index");
>   }
>
>   // 4. Build and send
>   const ixs = await sdk.orica.buildBuy(wallet.publicKey, userUsdc, market, amount, outcome);
>   const tx = new Transaction().add(...ixs);
>   return sendAndConfirmTransaction(connection, tx, [wallet]);
> }
> ```

> [tab] Python
>
> ```python theme={"dark"}
> import time
> from orica_sdk import MarketStatus
>
> async def safe_buy(market, amount, outcome):
>     # 1. Check market status
>     market_data = await sdk.orica.fetch_market(market)
>     if market_data.status != MarketStatus.OPEN:
>         raise ValueError("Market is not open for trading")
>
>     # 2. Check close time
>     now = int(time.time())
>     if market_data.close_time < now:
>         raise ValueError("Market has closed")
>
>     # 3. Check outcome is valid
>     if outcome >= market_data.outcome_count:
>         raise ValueError("Invalid outcome index")
>
>     # 4. Build and send
>     ixs = await sdk.orica.build_buy(wallet.pubkey(), user_usdc, market, amount, outcome)
>     tx = Transaction()
>     tx.add(*ixs)
>     return await connection.send_transaction(tx, wallet)
> ```

***

## Resource Links

* **TypeScript**: [GitHub](https://github.com/neko/orica-ts-sdk) · [Docs](https://neko.github.io/orica-ts-sdk/) · [NPM](https://github.com/neko/orica-ts-sdk/pkgs/npm/orica-sdk)
* **Python**: [GitHub](https://github.com/neko/orica-py-sdk) · [Docs](https://neko.github.io/orica-py-sdk/)

***

## Next Steps

> [card] [Error Handling](https://docs.orica.markets/sdk/error-handling.md)
>
> Handle errors gracefully.

> [card] [Types](https://docs.orica.markets/sdk/types.md)
>
> Complete type definitions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.