| Onboarding | Get started with Sai - your complete guide to setting up and accessing the platform for the first time | /pages/XBSTGOfOT1dnbU6mEVdx |
| Wallet Setup | Learn how to set up and connect your wallet to start trading on Sai | /pages/BbtbVLwFB6D5vbzJII9H |
| Acquiring Collateral | Discover how to obtain the necessary collateral to begin trading on the platform | /pages/edjOjvxVSQA6vJ8wGBqg |
| Choosing a Market | Understand how to select the right trading market based on your strategy and risk tolerance | /pages/yHmYbz1Q1squc3GVlCW6 |
| Sai Referral | Earn rewards and save on fees with Sai's referral program - invite traders and receive rewards | /pages/mWNWimKC8Kkbi71TGG7X |
Navigate to the Referrals page to create your unique code
Enter a referral code to unlock instant trading fee discounts
| EVM Integration Guide | Start here if you're building on EVM chains. Covers environment setup, contract connections, and basic operations like opening positions and managing collateral | /pages/x6GuM73eIeBDLjPxeM3A |
| WASM Integration Guide | For WASM-based chains and clients. Learn integration patterns with language-specific examples and deployment guidance | /pages/WKMKMdJjhQKkSZuv6kK2 |
| Perp Contract | Main perpetual futures contract handling position management, collateral, and settlement | /pages/CnCG6He36sdAh0t6mVAQ |
| Borrowing Module | Borrowed funds management, interest rates, and liquidation mechanics | /pages/b5Yoh7EqOvFi8DajOqK0 |
| Price Impact Module | How large trades affect pricing, slippage calculation, and execution costs | /pages/oIXiIdPoelXFFUwpf7D9 |
| State Variables | Complete reference of all smart contract state variables and their purposes | /pages/8vcCjjPMps4y8aQcoA7O |
| Contract Addresses Reference | Mainnet and testnet deployment addresses for all Sai contracts | /pages/Cc4tHnR3Je2ywLa2sbbC |
| WASM & EVM Integration | Platform-specific details for direct smart contract integration | /pages/evVIrw02t9H2IFuGuWEw |
| Core Concepts | Understand indexing, subscriptions, and how Keeper structures protocol data | /pages/wkWgBSrkIGBpygzvw8tl |
| Client Setup | Get your GraphQL client configured and authenticated in minutes | /pages/9bUolmzdEVNrHHABKeij |
| Perp API | Query positions, orders, trades, and perpetual-specific data | /pages/jAAxsXY92TQmt1Prwyex |
| Liquidity Provider (LP) API | Access liquidity pool data, provider positions, and performance metrics | /pages/nSP7xqSeaRwEXjWyOrYz |
| Oracle API | Get price feeds and oracle data used throughout the protocol | /pages/qtCydifRnuxRW8Y4L1SC |
| Fees API | Query fee structures, accruals, and historical fee data | /pages/IW1ai9xwPD43gLU5zd4A |
| Examples: Queries | Copy-paste ready GraphQL queries for common use cases | /pages/3bJuD90rJtFUL5eL7OLe |
| Examples: Subscriptions | See how to subscribe to real-time updates and build event-driven applications | /pages/DTpzlxWT14kpG0oP7Adj |
| Filters & Pagination | Master filtering, sorting, and pagination for efficient large-scale data retrieval | /pages/OH8OSiYwwfzuuIXbykP1 |
| Telegram Bot Integration | Build a Telegram trading bot with position monitoring, alerts, and order execution | /pages/bzk5b2zHGvi61jze31O7 |
Connecting to real-time feed...
}
```
### 3. Debounce Rapid Updates
```javascript
import { debounce } from 'lodash'
const debouncedUpdate = debounce((data) => {
updateUI(data)
}, 100)
const subscription = client.subscribe({
query: WATCH_PRICES
}).subscribe({
next: (data) => {
debouncedUpdate(data.tokenPricesUsd)
}
})
```
### 4. Combine with Queries for Initial Data
```javascript
// Fetch initial data with query
const { data: initialData } = await client.query({
query: GET_TRADES,
variables: { trader }
})
setTrades(initialData.perp.trades)
// Then subscribe to updates
const subscription = client.subscribe({
query: WATCH_TRADES,
variables: { trader }
}).subscribe({
next: (data) => {
setTrades(data.perpTrades)
}
})
```
# Client Setup
Set up GraphQL clients in various languages to interact with Sai Keeper API.
## Table of Contents
* [JavaScript/TypeScript](#javascripttypescript)
* [Apollo Client](#apollo-client)
* [urql](#urql)
* [GraphQL Request](#graphql-request)
* [Python](#python)
* [Rust](#rust)
* [Go](#go)
***
## JavaScript/TypeScript
### Apollo Client
Apollo Client is the most popular GraphQL client for JavaScript applications.
#### Installation
```bash
npm install @apollo/client graphql
# For subscriptions
npm install graphql-ws
```
#### Basic Setup (Queries Only)
```typescript
import { ApolloClient, InMemoryCache, HttpLink, gql } from '@apollo/client'
const client = new ApolloClient({
link: new HttpLink({
uri: 'https://sai-keeper.testnet-2.nibiru.fi/graphql'
}),
cache: new InMemoryCache()
})
// Example query
const GET_PRICES = gql`
query GetPrices {
oracle {
tokenPricesUsd(limit: 10) {
token { symbol }
priceUsd
}
}
}
`
async function fetchPrices() {
const { data, error } = await client.query({
query: GET_PRICES
})
if (error) {
console.error('Error:', error)
return
}
console.log('Prices:', data.oracle.tokenPricesUsd)
}
fetchPrices()
```
#### Full Setup (With Subscriptions)
```typescript
import {
ApolloClient,
InMemoryCache,
HttpLink,
split,
gql
} from '@apollo/client'
import { GraphQLWsLink } from '@apollo/client/link/subscriptions'
import { getMainDefinition } from '@apollo/client/utilities'
import { createClient } from 'graphql-ws'
// HTTP link for queries and mutations
const httpLink = new HttpLink({
uri: 'https://sai-keeper.testnet-2.nibiru.fi/graphql'
})
// WebSocket link for subscriptions
const wsLink = new GraphQLWsLink(
createClient({
url: 'wss://sai-keeper.testnet-2.nibiru.fi/graphql',
connectionParams: {
// Add authentication if needed
// authToken: 'your-auth-token'
},
retryAttempts: 5,
shouldRetry: () => true,
on: {
connected: () => console.log('WebSocket connected'),
closed: () => console.log('WebSocket closed'),
error: (error) => console.error('WebSocket error:', error)
}
})
)
// Split traffic between HTTP and WebSocket
const splitLink = split(
({ query }) => {
const definition = getMainDefinition(query)
return (
definition.kind === 'OperationDefinition' &&
definition.operation === 'subscription'
)
},
wsLink,
httpLink
)
const client = new ApolloClient({
link: splitLink,
cache: new InMemoryCache(),
defaultOptions: {
watchQuery: {
fetchPolicy: 'cache-and-network'
}
}
})
// Example subscription
const WATCH_PRICES = gql`
subscription WatchPrices {
tokenPricesUsd {
token { symbol }
priceUsd
}
}
`
const subscription = client.subscribe({
query: WATCH_PRICES
}).subscribe({
next: ({ data }) => {
console.log('Price update:', data.tokenPricesUsd)
},
error: (error) => {
console.error('Subscription error:', error)
}
})
// Clean up
// subscription.unsubscribe()
export default client
```
#### React Integration
```typescript
import { ApolloProvider, useQuery, useSubscription, gql } from '@apollo/client'
import client from './apollo-client'
// Wrap your app
function App() {
return (
Loading...
if (error) return Error: {error.message}
return (
{data.perp.trades.map(trade => (
)
}
// Use subscriptions in components
function PriceTicker() {
const WATCH_PRICES = gql`
subscription {
tokenPricesUsd {
token { symbol }
priceUsd
}
}
`
const { data, loading } = useSubscription(WATCH_PRICES)
if (loading) return
Trade #{trade.id} - PnL: {(trade.state.pnlPct * 100).toFixed(2)}%
))}
Connecting...
return (
{data.tokenPricesUsd.map(item => (
)
}
```
***
### urql
urql is a lightweight alternative to Apollo Client.
#### Installation
```bash
npm install urql graphql
# For subscriptions
npm install graphql-ws
```
#### Setup
```typescript
import { createClient, fetchExchange, subscriptionExchange } from 'urql'
import { createClient as createWSClient } from 'graphql-ws'
const wsClient = createWSClient({
url: 'wss://sai-keeper.testnet-2.nibiru.fi/graphql'
})
const client = createClient({
url: 'https://sai-keeper.testnet-2.nibiru.fi/graphql',
exchanges: [
fetchExchange,
subscriptionExchange({
forwardSubscription: (operation) => ({
subscribe: (sink) => ({
unsubscribe: wsClient.subscribe(operation, sink)
})
})
})
]
})
export default client
```
#### React Integration
```typescript
import { Provider, useQuery, useSubscription } from 'urql'
import client from './urql-client'
function App() {
return (
{item.token.symbol}: ${item.priceUsd.toFixed(2)}
))}
Loading...
if (error) return Error: {error.message}
return (
{data.perp.trades.map(trade => (
)
}
```
***
### GraphQL Request
Lightweight library for simple queries (no caching or subscriptions).
#### Installation
```bash
npm install graphql-request graphql
```
#### Usage
```typescript
import { GraphQLClient, gql } from 'graphql-request'
const client = new GraphQLClient(
'https://sai-keeper.testnet-2.nibiru.fi/graphql'
)
const GET_TRADES = gql`
query GetTrades($trader: String!) {
perp {
trades(where: { trader: $trader, isOpen: true }) {
id
isLong
leverage
}
}
}
`
async function fetchTrades(trader: string) {
try {
const data = await client.request(GET_TRADES, { trader })
console.log('Trades:', data.perp.trades)
return data.perp.trades
} catch (error) {
console.error('Error fetching trades:', error)
throw error
}
}
fetchTrades('nibi1abc...')
```
***
## Python
### gql Library
Full-featured GraphQL client for Python.
#### Installation
```bash
pip install gql[all]
```
#### Setup
```python
from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport
from gql.transport.websockets import WebsocketsTransport
import asyncio
# HTTP Transport for queries
http_transport = AIOHTTPTransport(
url="https://sai-keeper.testnet-2.nibiru.fi/graphql"
)
# Create client
client = Client(
transport=http_transport,
fetch_schema_from_transport=True
)
# Example query
async def get_trades(trader_address):
query = gql("""
query GetTrades($trader: String!) {
perp {
trades(where: { trader: $trader, isOpen: true }) {
id
isLong
leverage
state {
pnlPct
liquidationPrice
}
perpBorrowing {
baseToken {
symbol
}
}
}
}
}
""")
params = {"trader": trader_address}
async with Client(transport=http_transport) as session:
result = await session.execute(query, variable_values=params)
return result['perp']['trades']
# Run the query
trades = asyncio.run(get_trades("nibi1abc..."))
for trade in trades:
pnl_pct = trade['state']['pnlPct'] * 100
print(f"Trade #{trade['id']}: {trade['perpBorrowing']['baseToken']['symbol']} {trade['leverage']}x - PnL: {pnl_pct:.2f}%")
```
#### With Subscriptions
```python
from gql import gql, Client
from gql.transport.websockets import WebsocketsTransport
import asyncio
# WebSocket transport for subscriptions
ws_transport = WebsocketsTransport(
url="wss://sai-keeper.testnet-2.nibiru.fi/graphql"
)
async def watch_prices():
subscription = gql("""
subscription WatchPrices {
tokenPricesUsd {
token {
symbol
}
priceUsd
}
}
""")
async with Client(transport=ws_transport) as session:
async for result in session.subscribe(subscription):
prices = result['tokenPricesUsd']
for item in prices:
print(f"{item['token']['symbol']}: ${item['priceUsd']:.2f}")
# Run subscription
asyncio.run(watch_prices())
```
#### Synchronous Version
```python
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport
# Synchronous transport
transport = RequestsHTTPTransport(
url="https://sai-keeper.testnet-2.nibiru.fi/graphql",
verify=True,
retries=3
)
client = Client(transport=transport, fetch_schema_from_transport=True)
# Synchronous query
def get_token_prices():
query = gql("""
query GetPrices {
oracle {
tokenPricesUsd(limit: 10) {
token {
symbol
}
priceUsd
}
}
}
""")
result = client.execute(query)
return result['oracle']['tokenPricesUsd']
prices = get_token_prices()
for item in prices:
print(f"{item['token']['symbol']}: ${item['priceUsd']:.2f}")
```
***
## Rust
### graphql\_client
Type-safe GraphQL client for Rust.
#### Installation
Add to `Cargo.toml`:
```toml
[dependencies]
graphql_client = "0.13"
reqwest = { version = "0.11", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
```
#### Setup
```rust
use graphql_client::{GraphQLQuery, Response};
use reqwest;
// Define the query
#[derive(GraphQLQuery)]
#[graphql(
schema_path = "schema.graphql",
query_path = "queries/get_trades.graphql",
response_derives = "Debug"
)]
pub struct GetTrades;
#[tokio::main]
async fn main() -> Result<(), BoxTrade #{trade.id}
))}
 Discord | Chat, support, and announcements | https://discord.com/invite/saidotfun | |
 X / Twitter | @SaiDotFun — news and updates | https://x.com/SaiDotFun | |
 Telegram | News channel and alerts | https://t.me/saidotfun | |
 Instagram | @saidotfun | https://instagram.com/saidotfun | |
 TikTok | @saidotfun | https://www.tiktok.com/@saidotfun | |
 YouTube | @saidotfun | https://www.youtube.com/@saidotfun |
Trading made simple. Perps without limits.
Sai’s Trading Interface
Risk note: SLPs are the counterparty to traders. When traders profit, vaults can take losses. When traders lose, LPs earn fees.
Program Structure: The Tiers of SaiClone
How to Earn XP on SaiClone
Unlock Exclusive Bi-monthly Sage Rewards