Skip to content

Unique-Divine/jiyuu / ai-skills/sai

Trade and inspect Sai perpetuals on Nibiru with the open-source `sai` CLI and its MCP server, and query or reconcile Sai Perps data from live contracts, Sai Keeper GraphQL, and DexPal REST. Use for Sai markets, prices, positions, balances, trade history, live watches, connecting a Sai account, previewing or submitting trades, checking intents, installing or configuring the Sai MCP server, `sai config`, `sai doctor`, `sai update`, `sai logs`, fees, open interest, SLP vaults, referrals, or disagreements between on-chain and indexed data. Use agent skill `sai-ops` for contract and operator mutations.

FileKindSize
SKILL.mdskill md6.1 KB
cli.mdmarkdown11.0 KB
examples/prompts.mdmarkdown2.1 KB
mcp.mdmarkdown8.1 KB
references/contracts.mdmarkdown28.1 KB
references/graphql.mdmarkdown4.5 KB
references/reconciliation.mdmarkdown3.4 KB
references/referrals.mdmarkdown6.9 KB
references/rest.mdmarkdown7.1 KB
references/vaults.mdmarkdown23.7 KB
trading-safety.mdmarkdown11.2 KB

references/graphql.md

View on GitHub
# Sai Keeper GraphQL queries

Use this reference for indexed, app-facing Sai data: perp positions and
history, SLP Vault history, Oracle prices, referral analytics, and live
subscriptions. For live protocol state or contract-owned values, use
[`contracts.md`](contracts.md) instead.

## Source and endpoints

The deployed schema is the authority. Read it with a GraphQL introspection
query or in the playground at the host root. The endpoint path is `/query`.

| Network | HTTP | WebSocket |
| --- | --- | --- |
| Mainnet | `https://sai-keeper.nibiru.fi/query` | `wss://sai-keeper.nibiru.fi/query` |
| Testnet2 | `https://sai-keeper.testnet-2.nibiru.fi/query` | `wss://sai-keeper.testnet-2.nibiru.fi/query` |

Verify a field against the deployment you query. Mainnet and Testnet2 can
run different Keeper versions.

## Query domains

The root `Query` type exposes domain objects: `oracle`, `perp`, `lp`,
`referral`, `appVersion`, `saiPoints`, and `explorer`. Scope fields under their
domain rather than querying them at the root.

| Domain | Key fields | Notes |
| --- | --- | --- |
| `perp` | `trade`, `trades`, `tradeHistory`, `borrowing`, `borrowings`, `statsUserPortfolio`, `traderFeeTierProgress` | Indexed trades, market borrowing state, and portfolio/fee-tier summaries. `trades(where:)` requires a trader address. |
| `lp` | `vaults`, `depositHistory`, `withdrawRequests`, `vaultStats`, `epochDurationDays` | Indexed vault and LP history; not a replacement for live vault accounting. |
| `oracle` | `tokens`, `token`, `tokenPricesUsd` | App-indexed token metadata and prices. Use `lastUpdatedBlock` to assess freshness. |
| `referral` | `referralCodes`, `referralTrades`, `referralRedemption`, `referralRedemptionTrader`, `referralClaims`, `referralStats` | Historical referral data keyed by referrer or trader. |

There is no GraphQL `fee` root domain or fields such as `feeTransactions` in
the current schema. For fee details, use Perp trade history fields such as
`openingFeeUsd` and `closingFeeUsd`, contract fee queries, or database
references as appropriate.

## Filters, order, and units

- Perp query field `trades` uses `PerpTradesFilter`, whose required `trader`
  field can be narrowed by `perpMarketId`, `perpCollateralId`, and `isOpen`.
- Perp query field `tradeHistory` uses `PerpTradeHistoryFilter`, whose required
  `trader` field returns the trader's indexed mutations.
- Lists accept their schema-defined `order_by`, `order_desc`, `limit`, and
  `offset` arguments. Do not assume that an order enum applies to another
  domain.
- Many contract-sized values are GraphQL `Int` base units, including Perp trade
  collateral and open interest. Exceptions are deliberate: table `Balance`
  exposes `amount` as a string, and USD/price/percentage fields commonly use
  GraphQL `Float`.
- GraphQL type `Token` does not expose decimal metadata. Table `Balance` includes
  `token_info.decimals` when a wallet or Sai balance subscription is relevant.

## Subscriptions

The current `Subscription` type provides exactly these fields:

| Field | Required filter or arguments |
| --- | --- |
| `tokenPricesUsd` | Optional `SubTokenPriceUsdFilter` (`tokenId`) |
| `perpTrades` | `SubPerpTradesFilter!` (`trader`) |
| `perpTradeHistory` | `SubPerpTradeHistoryFilter!` (`trader`) |
| `perpBorrowings` | None |
| `perpBorrowing` | `marketId`, `collateralId` |
| `lpVaults` | None |
| `lpDepositHistory` | `SubLpDepositHistoryFilter!` (`depositor`, `vault`) |
| `lpWithdrawRequests` | `SubLpWithdrawRequestsFilter!` (`depositor`, `vault`) |
| `userBalances` | `SubUserBalancesFilter!` (`user`) |
| `userInfo` | `SubUserFilter!` (`user`) |

No `lpDeposits` subscription exists in the current schema. For a user’s vault
state, query the LP history/request fields or read live contract state according
to the fact being requested.

## Example queries

```graphql
query OpenTrades($trader: String!) {
  perp {
    trades(where: { trader: $trader, isOpen: true }) {
      id
      collateralAmount
      leverage
      isLong
      state { positionValue liquidationPrice }
    }
  }
}
```

```graphql
query ReferralHistory($referrer: String!) {
  referral {
    referralCodes(referrer: $referrer) { code active uniqueTraders volumeUSD }
    referralRedemption(referrer: $referrer) { trader code active block { block block_ts } }
  }
}
```

## Related references

- [`contracts.md`](contracts.md): live Perp, Oracle, and vault queries.
- [`rest.md`](rest.md): public aggregates rather than entity history.
- Private agent skill `sai-db`: table ownership, aggregation, and freshness.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall