### Install Skills via ClawHub

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/README.md

Commands to install specific skills for writing Sentio processors and interacting with the Sentio platform.

```bash
# Install Skill to write and debug Sentio processor
npx clawhub@latest install sentio-processor

# Install Skill to interact with Sentio queries, dashboard, alerts, etc
npx clawhub@latest install sentio-platform
```

--------------------------------

### package.json Project Setup

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Standard configuration for dependencies and CLI scripts in a Sentio project.

```json
{
  "name": "my-sentio-processor",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "sentio build",
    "gen": "sentio gen",
    "upload": "sentio upload",
    "test": "sentio test",
    "dev": "sentio build --watch"
  },
  "dependencies": {
    "@sentio/sdk": "^3.4.0"
  },
  "devDependencies": {
    "@sentio/cli": "^3.4.0",
    "typescript": "^5.4.5"
  }
}
```

--------------------------------

### Install Claude Code Plugin

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/README.md

Commands to add the repository as a marketplace source and install the plugin for Claude Code.

```bash
# Add this repo as a marketplace source
/plugin marketplace add sentioxyz/sentio-ai-kit

# Install the plugin
/plugin install sentio-ai-kit
```

--------------------------------

### sentio.yaml Configuration Example

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Configure project settings, including project name, environment host, and contract definitions for EVM and Move chains.

```yaml
# sentio.yaml
project: myorg/my-indexer  # Required: owner/project-name

host: prod                  # Environment: prod | test | staging | local

# Contract definitions
contracts:
  # EVM contracts (use numeric chain IDs as strings)
  - chain: "1"              # Ethereum mainnet
    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    name: "USDC"

  - chain: "137"            # Polygon
    address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
    name: "USDC_Polygon"

  - chain: "42161"          # Arbitrum
    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    name: "USDC_Arbitrum"

  # Move chains (use chain names)
  - chain: aptos_mainnet
    address: "0x1"
    name: "coin"

  - chain: sui_mainnet
    address: "0xdee9::clob_v2"
    name: "deepbook"

```

--------------------------------

### Set Up and Run Processor Tests

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Initialize TestProcessorServer with your processor file. Use before() to start the server and then use chain-specific test methods like service.eth.testLog() to simulate events and assert results.

```typescript
import { TestProcessorServer, firstCounterValue } from '@sentio/sdk/testing'

const service = new TestProcessorServer(() => import('./processor.js'))
before(async () => { await service.start() })

// Ethereum
const resp = await service.eth.testLog(mockTransferLog('0x...', { from, to, value }))
assert.equal(firstCounterValue(resp.result, 'transfers'), 1n)
```

--------------------------------

### Required Setup for Sentio SDK

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/position-tracking-templates.md

Imports necessary modules from the Sentio SDK and configures execution to be sequential. Ensure these imports are present before using other SDK features.

```typescript
import { GLOBAL_CONFIG } from "@sentio/runtime";
import { BigDecimal } from "@sentio/sdk";
import { EthContext, isNullAddress } from "@sentio/sdk/eth";
import { ERC20Processor } from "@sentio/sdk/eth/builtin";
import { AccountSnapshot } from "./schema/store.js";

GLOBAL_CONFIG.execution = { sequential: true };
```

--------------------------------

### Implement Points System with Store (Lombard)

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/production-examples.md

This example demonstrates a points system for the Lombard protocol, tracking user balances and calculating daily points. It uses `onEventTransfer` and `onTimeInterval` to update user snapshots stored in the database. Ensure `GLOBAL_CONFIG.execution.sequential` is set to true for correct sequential processing.

```typescript
import { GLOBAL_CONFIG } from "@sentio/runtime"
import { BigDecimal } from "@sentio/sdk"
import { ERC20Processor } from "@sentio/sdk/eth/builtin"
import { isNullAddress } from "@sentio/sdk/eth"
import { AccountSnapshot } from "./schema/store.js"
import { getERC20ContractOnContext } from "@sentio/sdk/eth/builtin/erc20"

GLOBAL_CONFIG.execution = { sequential: true }

const DAILY_POINTS = 1000
const MULTIPLIER = 2
const MS_PER_DAY = 86400000
const TOKEN_DECIMALS = 8

ERC20Processor.bind({ network: NETWORK, address: VAULT_ADDRESS })
  .onEventTransfer(async (event, ctx) => {
    const newSnapshots = await Promise.all(
      [
        event.args.from,
        event.args.to
      ]
        .filter(a => !isNullAddress(a))
        .map(a => process(ctx, a, undefined, "Transfer"))
    )
    await ctx.store.upsert(newSnapshots)
  })
  .onTimeInterval(async (_, ctx) => {
    const accounts = await ctx.store.list(AccountSnapshot, [])
    const newSnapshots = await Promise.all(
      accounts.map(a => process(ctx, a.id.toString(), a, "TimeInterval"))
    )
    await ctx.store.upsert(newSnapshots)
  }, 60, 4 * 60)

async function process(ctx, account, snapshot, trigger) {
  if (!snapshot) snapshot = await ctx.store.get(AccountSnapshot, account)
  const points = snapshot ? calcPoints(ctx, snapshot) : new BigDecimal(0)

  const [lbtcTotal, lpBalance, totalSupply] = await Promise.all([
    getERC20ContractOnContext(ctx, LBTC_ADDRESS).balanceOf(VAULT_ADDRESS),
    ctx.contract.balanceOf(account),
    ctx.contract.totalSupply(),
  ])

  const newSnapshot = new AccountSnapshot({
    id: account,
    timestampMilli: BigInt(ctx.timestamp.getTime()),
    lbtcBalance: (lbtcTotal * lpBalance) / totalSupply,
  })

  ctx.eventLogger.emit("point_update", {
    account,
    points,
    trigger,
    newBalance: newSnapshot.lbtcBalance.scaleDown(TOKEN_DECIMALS),
    multiplier: MULTIPLIER,
  })
  return newSnapshot
}

function calcPoints(ctx, snapshot) {
  const deltaDay = (ctx.timestamp.getTime() - Number(snapshot.timestampMilli)) / MS_PER_DAY
  return snapshot.lbtcBalance
    .scaleDown(TOKEN_DECIMALS)
    .multipliedBy(DAILY_POINTS)
    .multipliedBy(deltaDay)
    .multipliedBy(MULTIPLIER)
}

```

--------------------------------

### Start Sui Processor with Checkpoint

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/advanced-patterns.md

For Sui processors, use `startCheckpoint` with a BigInt value to specify the starting point for processing, instead of `startBlock`.

```typescript
mint.bind({
  startCheckpoint: 8500000n  // Note: BigInt
})
  .onEventMintEvent(handler)
```

--------------------------------

### Setup ERC20 Transfer Processor Tests

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Use TestProcessorServer to mock EVM logs and assert counter values. Ensure the service is started before tests and stopped after.

```typescript
import { TestProcessorServer, firstCounterValue, firstGaugeValue } from '@sentio/sdk/testing'
import { expect } from 'chai'
import { BigDecimal } from '@sentio/sdk'

describe('ERC20 Transfer Processor', () => {
  const service = new TestProcessorServer(() => import('./processor.js'))

  before(async () => {
    await service.start()
  })

  after(async () => {
    await service.stop()
  })

  it('should count transfers', async () => {
    // Create mock transfer event
    const mockLog = {
      address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      topics: [
        '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef', // Transfer topic
        '0x000000000000000000000000' + 'aabbccdd'.repeat(5), // from
        '0x000000000000000000000000' + '11223344'.repeat(5), // to
      ],
      data: '0x0000000000000000000000000000000000000000000000000000000000000064', // 100
      blockNumber: 15000000,
      transactionHash: '0x' + 'ab'.repeat(32),
      transactionIndex: 0,
      blockHash: '0x' + 'cd'.repeat(32),
      logIndex: 0,
      removed: false,
    }

    const resp = await service.eth.testLog(mockLog)

    expect(firstCounterValue(resp.result, 'transfers')).to.equal(1n)
  })

  it('should emit transfer events', async () => {
    const mockLog = {
      address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      topics: [
        '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
        '0x000000000000000000000000' + 'aabbccdd'.repeat(5),
        '0x000000000000000000000000' + '11223344'.repeat(5),
      ],
      data: '0x00000000000000000000000000000000000000000000000000000000000f4240', // 1_000_000 (1 USDC)
      blockNumber: 15000000,
      transactionHash: '0x' + 'ab'.repeat(32),
      transactionIndex: 0,
      blockHash: '0x' + 'cd'.repeat(32),
      logIndex: 0,
      removed: false,
    }

    const resp = await service.eth.testLog(mockLog)

    const events = resp.result.events
    expect(events).to.have.lengthOf(1)
    expect(events[0].name).to.equal('Transfer')
    expect(events[0].attributes.amount).to.equal('1') // 1_000_000 / 10^6 = 1
  })
})
```

```typescript
import { TestProcessorServer, firstCounterValue, firstGaugeValue } from '@sentio/sdk/testing'
import { expect } from 'chai'
import { BigDecimal } from '@sentio/sdk'

describe('Aptos DEX Processor', () => {
  const service = new TestProcessorServer(() => import('./processor.js'))

  before(async () => { await service.start() })

  it('should track swap events', async () => {
    const mockEvent = {
      type: '0x190d44266241744264b964a37b8f09863167a12d3e70cda39376cfb4e3561e12::liquidity_pool::SwapEvent<0x1::aptos_coin::AptosCoin, 0x...::usdc::USDC, 0x190d44266241744264b964a37b8f09863167a12d3e70cda39376cfb4e3561e12::curves::Uncorrelated>',
      data: {
        x_in: '1000000000', // 10 APT
        x_out: '0',
        y_in: '0',
        y_out: '50000000', // 50 USDC
      },
      sequence_number: '100',
      guid: { account_address: '0x1', creation_number: '0' },
    }

    const resp = await service.aptos.testEvent(mockEvent)

    expect(resp.result.events).to.have.length.greaterThan(0)
  })
})
```

```typescript
import { TestProcessorServer, firstCounterValue, firstGaugeValue } from '@sentio/sdk/testing'
import { expect } from 'chai'
import { BigDecimal } from '@sentio/sdk'

describe('Sui DEX Processor', () => {
  const service = new TestProcessorServer(() => import('./processor.js'))

  before(async () => { await service.start() })

  it('should track swap events', async () => {
    const mockEvent = {
      type: '0x...::pool::SwapEvent',
      parsedJson: {
        pool: '0x...',
        amount_in: '1000000000',
        amount_out: '500000000',
        atob: true,
        fee_amount: '3000000',
      },
      sender: '0x...',
    }

    const resp = await service.sui.testEvent(mockEvent)

    expect(firstCounterValue(resp.result, 'swaps')).to.be.greaterThan(0n)
  })
})
```

--------------------------------

### Claude Code Usage Examples

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/README.md

Example natural language prompts for Claude Code to perform tasks within a Sentio project.

```text
"Create a Sentio processor that tracks USDC transfers on Ethereum"
"Add a Sui DEX swap tracker with volume metrics"
"Set up a points system for staking rewards"
```

--------------------------------

### Partition Events by Sender

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/advanced-patterns.md

Example of partitioning event data based on the sender's address for scalable processing. This allows for more efficient data handling.

```typescript
.onEventTransfer(handler, undefined, {
  partitionKey: (event) => event.args.from  // Partition by sender
})
```

--------------------------------

### Define Multi-Entity Schema for Lending Protocol

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/store-and-points.md

Example schema definition for a lending protocol, including supply and borrow balances for an AccountSnapshot entity.

```graphql
type AccountSnapshot @entity {
  id: String!
  timestampMilli: BigInt!
  supplyBalance: BigInt!
  borrowBalance: BigInt!
}
```

--------------------------------

### Bind Pendle SY, YT, LP, and Third-Party Staking Processors

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/position-tracking-templates.md

Binds different Pendle token processors (SY, YT, LP) and third-party staking contracts (Equilibria, Penpie) to handle their respective events and time intervals. Requires network and start block configurations.

```typescript
ERC20Processor.bind({ address: SY, network, startBlock: SY_START_BLOCK, name: "SY" })
  .onEventTransfer(async (evt, ctx) => await handleSYTransfer(evt, ctx));

// YT token (Yield Token)
PendleYieldTokenProcessor.bind({ address: YT, network, startBlock, name: "YT" })
  .onEventTransfer(async (evt, ctx) => await handleYTTransfer(evt, ctx))
  .onTimeInterval(async (_, ctx) => await processAllYTAccounts(ctx), 60, 60);

// LP token (Market)
PendleMarketProcessor.bind({ address: LP, network, startBlock, name: "LP" })
  .onEventTransfer(async (evt, ctx) => await handleLPTransfer(evt, ctx))
  .onEventSwap(async (evt, ctx) => await handleMarketSwap(evt, ctx));

// Third-party Liquid Locker (Equilibria / Penpie) staking events
EQBBaseRewardProcessor.bind({ address: EQB_RECEIPT_TOKEN, network, startBlock })
  .onEventStaked(async (evt, ctx) =>
    await processAllLPAccounts(ctx, [evt.args._user.toLowerCase()])
  )
  .onEventWithdrawn(async (evt, ctx) =>
    await processAllLPAccounts(ctx, [evt.args._user.toLowerCase()])
  );
```

--------------------------------

### Initialize Sentio Projects

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands to scaffold new indexing projects for various blockchain networks.

```bash
# Create Ethereum project
sentio create my-eth-indexer --chain-type eth --chain-id 1

# Create Aptos project
sentio create my-aptos-indexer --chain-type aptos

# Create Sui project
sentio create my-sui-indexer --chain-type sui

# Create Solana project
sentio create my-solana-indexer --chain-type solana

# Monorepo mode (no root dependencies)
sentio create my-subproject --chain-type eth --subproject
```

--------------------------------

### Initialize Aptos DEX Processor and Register Metrics

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Sets up metrics for volume, TVL, and pool counts, then initializes the AptosDex helper for LiquidSwap. Ensure all necessary SDK modules are imported.

```typescript
import { AptosNetwork, AptosResourcesProcessor } from "@sentio/sdk/aptos"
import { AptosDex, getPairValue } from "@sentio/sdk/aptos/ext"
import { Gauge, Counter } from "@sentio/sdk"
import { liquidity_pool } from "./types/aptos/liquidswap.js"

// Register metrics
const volume = Gauge.register("volume", { sparse: true })
const volumeByCoin = Gauge.register("volume_by_coin", { sparse: true })
const tvlAll = Gauge.register("tvl_all", { sparse: true })
const tvl = Gauge.register("tvl", { sparse: true })
const tvlByPool = Gauge.register("tvl_by_pool", { sparse: true })
const numPools = Counter.register("num_pools")

// Initialize AptosDex helper
const liquidSwap = new AptosDex(volume, volumeByCoin, tvlAll, tvl, tvlByPool, {
  getXReserve: pool => pool.coin_x_reserve.value,
  getYReserve: pool => pool.coin_y_reserve.value,
  getExtraPoolTags: pool => ({ curve: pool.type_arguments[2] }),
  poolType: liquidity_pool.LiquidityPool.type()
})
```

--------------------------------

### Define Multi-Entity Schema for NFT Position

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/store-and-points.md

Example schema definitions for NFT positions, including PositionSnapshot and StakedPositionSnapshot entities with relevant fields.

```graphql
type PositionSnapshot @entity {
  id: String!
  owner: String!
  tickLower: BigInt!
  tickUpper: BigInt!
  timestampMilli: BigInt!
  token0Balance: BigDecimal!
  token1Balance: BigDecimal!
}

type StakedPositionSnapshot @entity {
  id: String!
  owner: String!
}
```

--------------------------------

### Initialize Sentio Project

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Use to create a new Sentio indexing project. Specify the chain type and ID for initialization.

```bash
sentio create <project-name> --chain-type <type> --chain-id <id>
```

--------------------------------

### Add Contracts and Generate Types

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Integrates smart contracts into your project by downloading ABIs and generating TypeScript bindings. Use `sentio build` for a full generation and type-checking process.

```bash
sentio add <address> --chain <chain> --name <Name>   # Downloads ABI, updates sentio.yaml
```

```bash
sentio gen                                             # Generate TypeScript bindings
```

```bash
sentio build                                           # Full: gen + typecheck + bundle
```

--------------------------------

### Get Entity by ID using Store API

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Retrieves a single entity from the store by its unique identifier. Ensure the User entity is defined.

```typescript
async function getUser(ctx: EthContext, id: string): Promise<User | undefined> {
  return await ctx.store.get(User, id)
}
```

--------------------------------

### Manage Sentio Projects

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands for listing, retrieving, creating, and deleting projects.

```bash
sentio project list
```

```bash
sentio project get <owner>/<slug>
```

```bash
sentio project create --owner <owner> --name <name> --type sentio --visibility private
```

```bash
sentio project delete <owner>/<slug>
```

--------------------------------

### Get Underlying Balance from cToken

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/position-tracking-templates.md

Converts a cToken balance to its underlying asset amount using the `exchangeRateStored` function. Requires the cToken contract address and the account's balance.

```typescript
async function getBalance(ctx: EthContext, account: string): Promise<bigint> {
  const cToken = getCTokenContractOnContext(ctx, CTOKEN_ADDRESS);
  const [balance, rate] = await Promise.all([
    cToken.balanceOf(account),
    cToken.exchangeRateStored(),
  ]);
  // cToken balance * exchange rate / 1e18 = underlying amount
  return (balance * rate) / BigInt(1e18);
}
```

--------------------------------

### Run Simulations

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands for executing transaction and bundle simulations, and retrieving simulation results.

```bash
sentio simulation run --project <owner>/<slug> --file sim.yaml
```

```bash
sentio simulation run-bundle --project <owner>/<slug> --chain-id <id> --file bundle.yaml
```

```bash
sentio simulation list --project <owner>/<slug>
```

```bash
sentio simulation get <simulation-id> --project <owner>/<slug>
```

```bash
sentio simulation bundle --project <owner>/<slug>
```

```bash
sentio simulation trace --project <owner>/<slug>
```

--------------------------------

### Authentication and Deployment

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands for managing user authentication and deploying processor code to the Sentio platform.

```bash
# Login via OAuth browser flow
sentio login

# Login with API key
sentio login --api-key YOUR_API_KEY

# Login to test environment
sentio login --host test

# Check login status
npx @sentio/cli@latest login --status

# Deploy processor (builds automatically)
sentio upload

# Deploy without rebuilding
sentio upload --skip-build

# Hot-swap without re-indexing (continues from latest version)
sentio upload --continue-from 5

# Rollback to specific block checkpoint
sentio upload --checkpoint "1:18000000"

# Parallel workers for compute-heavy processors
sentio upload --num-workers=4
```

--------------------------------

### Get Token Price and Calculate USD Value

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Use getPriceByType and token.getERC20TokenInfo to fetch token details and prices. Calculate the USD value of an amount by scaling down and multiplying by the price.

```typescript
import { getPriceByType, token } from "@sentio/sdk/utils"

const info = await token.getERC20TokenInfo(EthChainId.ETHEREUM, tokenAddr)
const price = await getPriceByType(EthChainId.ETHEREUM, tokenAddr, ctx.timestamp) || 0
const usdValue = amount.scaleDown(info.decimal).multipliedBy(price)
```

--------------------------------

### Manage Projects and Processors

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands for project lifecycle management and monitoring processor status and logs.

```bash
sentio project list
```

```bash
sentio project get owner/project-name
```

```bash
sentio project create --owner myorg --name my-indexer --type sentio --visibility private
```

```bash
sentio project delete owner/project-name
```

```bash
sentio processor status --project owner/project-name
```

```bash
sentio processor source --project owner/project-name
```

```bash
sentio processor activate-pending --project owner/project-name
```

```bash
sentio processor pause --project owner/project-name --reason "maintenance" -y
sentio processor resume --project owner/project-name
sentio processor stop --project owner/project-name
```

```bash
sentio processor logs --project owner/project-name --limit 100
```

```bash
sentio processor logs --project owner/project-name -f
```

```bash
sentio processor logs --project owner/project-name --log-type execution --level ERROR --query "timeout"
```

--------------------------------

### Get Token USD Value with Caching

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/defi-patterns.md

Caches token info to avoid repeated RPC calls and calculates the USD value of a token amount. Requires `getPriceByType` and `token.getERC20TokenInfo` from `@sentio/sdk/utils`.

```typescript
import { getPriceByType, token } from "@sentio/sdk/utils"

// Cache token info to avoid repeated RPC calls
let tokenMap = new Map<string, Promise<token.TokenInfo | undefined>>()

async function getOrCreateToken(ctx: EthContext, address: string) {
  let infoPromise = tokenMap.get(address)
  if (!infoPromise) {
    infoPromise = token.getERC20TokenInfo(ctx.chainId, address)
    tokenMap.set(address, infoPromise)
  }
  return infoPromise
}

// Get USD value of a token amount
async function getUsdValue(ctx: EthContext, tokenAddr: string, amount: bigint) {
  const info = await getOrCreateToken(ctx, tokenAddr)
  if (!info) return BigDecimal(0)
  const price = await getPriceByType(ctx.chainId, tokenAddr, ctx.timestamp) || 0
  return amount.scaleDown(info.decimal).multipliedBy(price)
}
```

--------------------------------

### Manage Contracts and Bindings

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands to add contract ABIs and generate TypeScript bindings for project development.

```bash
# Add contract by address (auto-fetches ABI from explorer)
sentio add 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain 1 --name USDC

# Add Aptos module
sentio add 0x1 --chain aptos_mainnet --name coin

# Add Sui package
sentio add 0xdee9... --chain sui_mainnet --name deepbook

# Generate TypeScript bindings from ABIs
sentio gen

# Full build: gen + typecheck + bundle
sentio build
```

--------------------------------

### Endpoint Management

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands to create, list, test, and delete project endpoints.

```bash
sentio endpoint create --project <owner>/<slug> --query "SELECT * FROM t WHERE amount > \${min}" --args '{"min":"int"}'
```

```bash
sentio endpoint list --project <owner>/<slug>
```

```bash
sentio endpoint get --project <owner>/<slug> --id <id>
```

```bash
sentio endpoint test --project <owner>/<slug> --id <id> --args '{"min":1000}'
```

```bash
sentio endpoint delete --project <owner>/<slug> --id <id>
```

--------------------------------

### Define and Use Store Entities

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Define entities in schema.graphql and use the store API to get, upsert, list, and delete them. Enable sequential execution for store operations to prevent race conditions.

```graphql
type AccountSnapshot @entity {
  id: ID!
  timestampMilli: BigInt!
  balance: BigInt!
}
```

```typescript
import { AccountSnapshot } from "./schema/store.js"

await ctx.store.get(AccountSnapshot, id)
await ctx.store.upsert(new AccountSnapshot({ id, timestampMilli, balance }))
await ctx.store.list(AccountSnapshot, [])  // List all
await ctx.store.delete(AccountSnapshot, id)
```

```typescript
import { GLOBAL_CONFIG } from "@sentio/runtime"
GLOBAL_CONFIG.execution = { sequential: true }
```

--------------------------------

### Manage Dashboards and Panels

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands for listing, creating, importing/exporting dashboards, and adding various panel types.

```bash
sentio dashboard list --project owner/project-name
```

```bash
sentio dashboard create --project owner/project-name --title "My Dashboard"
```

```bash
sentio dashboard create --project owner/project-name --file dashboard.json
```

```bash
sentio dashboard export dashboard-id-123 --project owner/project-name
```

```bash
sentio dashboard import dashboard-id-123 --project owner/project-name --file dashboard.json
```

```bash
sentio dashboard add-panel dashboard-id-123 --project owner/project-name \
  --panel-name "Top Holders" \
  --type TABLE \
  --sql "SELECT address, balance FROM accounts ORDER BY balance DESC LIMIT 50"
```

```bash
sentio dashboard add-panel dashboard-id-123 --project owner/project-name \
  --panel-name "Transfer Count" \
  --type LINE \
  --event Transfer \
  --aggr total
```

```bash
sentio dashboard add-panel dashboard-id-123 --project owner/project-name \
  --panel-name "Volume by Pool" \
  --type BAR \
  --metric swap_volume \
  --filter amount>1000 \
  --group-by pool_name \
  --func 'topk(5)'
```

```bash
sentio dashboard add-panel dashboard-id-123 --project owner/project-name \
  --panel-name "24h ETH Price" \
  --type LINE \
  --metric eth_price \
  --time-range-start -24h \
  --time-range-end now \
  --time-range-step 3600
```

--------------------------------

### Perform CRUD Operations with Sentio Store

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/store-and-points.md

Utilize the Sentio store for common database operations like getting, upserting, listing, and deleting entities. Ensure necessary imports from the generated schema.

```typescript
import { AccountSnapshot } from "./schema/store.js"

// Get by ID
const snapshot = await ctx.store.get(AccountSnapshot, accountId)

// Upsert (create or update)
await ctx.store.upsert(new AccountSnapshot({
  id: account,
  timestampMilli: BigInt(ctx.timestamp.getTime()),
  balance: newBalance,
}))

// Batch upsert
const snapshots = accounts.map(a => new AccountSnapshot({ ... }))
await ctx.store.upsert(snapshots)

// List with filters (loads all into memory)
const users = await ctx.store.list(AccountSnapshot, [
  { field: "balance", op: ">", value: 0 },
  { field: "name", op: "=", value: "Alice" },
])

// List all entities (empty filter required)
const allAccounts = await ctx.store.list(AccountSnapshot, [])

// Iterator (memory-efficient for large datasets)
for await (const user of ctx.store.listIterator(AccountSnapshot, [
  { field: "balance", op: ">", value: 0 },
])) {
  // process one at a time
}

// Delete
await ctx.store.delete(AccountSnapshot, accountId)
```

--------------------------------

### Data Querying

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands to retrieve events, metrics, and price data from projects.

```bash
sentio data events --project <owner>/<slug>
```

```bash
sentio data metrics --project <owner>/<slug>
```

```bash
sentio data query --project <owner>/<slug> --event Transfer --aggr total --group-by timestamp
```

```bash
sentio data query --project <owner>/<slug> --metric burn --aggr avg --filter meta.chain=1
```

```bash
sentio data query --project <owner>/<slug> --price ETH
```

```bash
sentio data query --doc
```

--------------------------------

### Login and Deploy Processor

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Handles authentication and deployment of your Sentio processor. Supports OAuth, API key authentication, and targeting test environments. Deployment options include skipping the build step or continuing from a previous version.

```bash
sentio login                              # OAuth browser flow (prod)
```

```bash
sentio login --api-key <key>              # API key auth
```

```bash
sentio login --host test                  # Target test environment
```

```bash
sentio upload                             # Build + deploy
```

```bash
sentio upload --skip-build                # Deploy only
```

```bash
sentio upload --continue-from <ver>       # Hot-swap without re-indexing
```

```bash
sentio upload --checkpoint "1:18000000"   # Rollback to specific block
```

```bash
sentio upload --num-workers=4             # Parallel workers for compute-heavy processors
```

--------------------------------

### Create and Manage Alerts

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands for creating various alert types (metric, event, log, SQL) and managing existing alert rules.

```bash
sentio alert create --project owner/project-name \
  --type METRIC \
  --subject "Burn spike detected" \
  --metric burn \
  --aggr avg \
  --op '>' \
  --threshold 100
```

```bash
sentio alert create --project owner/project-name \
  --type METRIC \
  --subject "Transfer anomaly" \
  --event Transfer \
  --filter amount>0 \
  --aggr total \
  --func 'delta(1m)' \
  --op '>' \
  --threshold 100
```

```bash
sentio alert create --project owner/project-name \
  --type LOG \
  --subject "Large transfers" \
  --query 'amount:>1000' \
  --op '>' \
  --threshold 0
```

```bash
sentio alert create --project owner/project-name \
  --type SQL \
  --subject "Whale activity" \
  --query 'SELECT timestamp, amount FROM transfer WHERE amount > 1000' \
  --time-column timestamp \
  --value-column amount \
  --sql-aggr MAX \
  --op '>' \
  --threshold 1000
```

```bash
sentio alert create --project owner/project-name \
  --type METRIC --subject "Alert" --metric volume --aggr sum --op '>' --threshold 100 \
  --for 5m --interval 1m
```

```bash
sentio alert create --project owner/project-name \
  --type METRIC --subject "Range alert" --metric price --aggr avg \
  --op between --threshold 10 --threshold2 100
```

```bash
sentio alert update rule-id-123 --project owner/project-name --file updated.yaml
```

```bash
sentio alert delete rule-id-123 --project owner/project-name
```

--------------------------------

### SQL Query Execution

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands for executing, paginating, and managing SQL queries against Sentio projects.

```bash
sentio data sql --project <owner>/<slug> --query "SELECT * FROM transfer LIMIT 10"
```

```bash
sentio data sql --project <owner>/<slug> --query "..." --async
```

```bash
sentio data sql --project <owner>/<slug> --result <execution-id>
```

```bash
sentio data sql --project <owner>/<slug> --cursor <cursor>
```

```bash
sentio data sql --project <owner>/<slug> --file query.yaml
```

--------------------------------

### Manage API Endpoints

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands for creating, testing, and managing SQL-based REST API endpoints.

```bash
sentio endpoint create --project owner/project-name \
  --query "SELECT * FROM transfers WHERE amount > ${min}" \
  --args '{"min":"int"}'
```

```bash
sentio endpoint list --project owner/project-name
```

```bash
sentio endpoint get --project owner/project-name --id endpoint-id-123
```

```bash
sentio endpoint test --project owner/project-name --id endpoint-id-123 --args '{"min":1000}'
```

```bash
sentio endpoint delete --project owner/project-name --id endpoint-id-123
```

--------------------------------

### Implement Aptos Processor

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Binds to Aptos network to handle coin events.

```typescript
import { AptosNetwork } from '@sentio/sdk/aptos'
import { coin } from '@sentio/sdk/aptos/builtin/0x1'

coin.bind({ network: AptosNetwork.MAIN_NET })
  .onEventWithdrawEvent(async (evt, ctx) => {
    ctx.meter.Counter('withdrawals').add(1)
    ctx.eventLogger.emit('Withdraw', {
      distinctId: evt.guid.account_address,
      amount: evt.data_decoded.amount,
    })
  })
```

--------------------------------

### Call Aptos View Function

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/advanced-patterns.md

Demonstrates how to call a Move view function on Aptos to retrieve data, such as coin supply. Ensure the correct network and coin type are specified.

```typescript
import { coin } from '@sentio/sdk/aptos/builtin/0x1'

coin.bind({ network: AptosNetwork.MAIN_NET })
  .onEventWithdrawEvent(async (evt, ctx) => {
    // Call a Move view function
    const [res] = await coin.view.supply(ctx.getClient(), {
      typeArguments: ['0x1::aptos_coin::AptosCoin']
    })
    if (res.vec.length > 0) {
      ctx.meter.Gauge('supply').record(res.vec[0])
    }
  })
```

--------------------------------

### Track DEX Volume and TVL with AptosDex

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/defi-patterns.md

Use the AptosDex helper class to standardize volume and TVL tracking for Aptos-based DEX pools.

```typescript
import { AptosDex, getPairValue } from "@sentio/sdk/aptos/ext"

const liquidSwap = new AptosDex<PoolType<any, any, any>>(
  volume, volumeByCoin, tvlAll, tvl, tvlByPool, {
    getXReserve: pool => pool.coin_x_reserve.value,
    getYReserve: pool => pool.coin_y_reserve.value,
    getExtraPoolTags: pool => ({ curve: pool.type_arguments[2] }),
    poolType: liquidity_pool.LiquidityPool.type()
  }
)

// In swap handler:
const value = await liquidSwap.recordTradingVolume(ctx,
  evt.type_arguments[0], evt.type_arguments[1],
  evt.data_decoded.x_in + evt.data_decoded.x_out,
  evt.data_decoded.y_in + evt.data_decoded.y_out,
  { curve: getCurve(evt.type_arguments[2]) }
)
```

--------------------------------

### CLI Price Data Commands

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Use these commands to interact with price data via the Sentio CLI.

```bash
sentio price get --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain 1
```

```bash
sentio price get --coin ETH --timestamp 1704067200
```

```bash
sentio price batch --file prices.yaml
```

```bash
sentio price coins
```

```bash
sentio price check-latest
```

--------------------------------

### Plugin Directory Structure

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/README.md

The file structure of the sentio-ai-kit repository.

```text
sentio-ai-kit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── sentio-processor/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── advanced-patterns.md
│   │       ├── defi-patterns.md
│   │       ├── store-and-points.md
│   │       └── production-examples.md
│   └── sentio-platform/
│       └── SKILL.md
└── README.md
```

--------------------------------

### Manage Sentio Dashboards

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands for listing, creating, exporting, and importing dashboards, as well as adding various panel types.

```bash
sentio dashboard list --project <owner>/<slug>
```

```bash
sentio dashboard create --project <owner>/<slug> --title "My Dashboard"
```

```bash
sentio dashboard create --project <owner>/<slug> --file dashboard.json
```

```bash
sentio dashboard export <dashboardId> --project <owner>/<slug>
```

```bash
sentio dashboard import <dashboardId> --project <owner>/<slug> --file dashboard.json
```

```bash
sentio dashboard import <dashboardId> --project <owner>/<slug> --stdin
```

```bash
sentio dashboard import <dashboardId> --project <owner>/<slug> --file dashboard.json --override-layouts
```

```bash
sentio dashboard add-panel <dashboardId> --project <owner>/<slug> --panel-name "Top Holders" --type TABLE --sql "SELECT * FROM CoinBalance ORDER BY balance DESC LIMIT 50"
```

```bash
sentio dashboard add-panel <dashboardId> --project <owner>/<slug> --panel-name "Transfer Count" --type LINE --event Transfer --aggr total
```

```bash
sentio dashboard add-panel <dashboardId> --project <owner>/<slug> --panel-name "ETH Price" --type LINE --metric cbETH_price
```

--------------------------------

### Define Project Structure

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Standard directory layout for a Sentio project.

```text
my-project/
  sentio.yaml              # Project config
  schema.graphql           # Store entity definitions (optional)
  package.json             # @sentio/sdk + @sentio/cli deps
  tsconfig.json
  abis/{chain}/            # Contract ABIs
  src/
    processor.ts           # Main processor code
    processor.test.ts      # Tests
    types/                 # Auto-generated (sentio gen)
    schema/                # Auto-generated store entities
  dist/lib.js              # Bundled output (sentio build)
```

--------------------------------

### Manage Alerts

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Commands to list and retrieve details for alert rules configured on a project.

```bash
# List all alerts
sentio alert list --project owner/project-name

# Get specific alert details
sentio alert get rule-id-123 --project owner/project-name
```

--------------------------------

### Project Configuration YAML

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Configuration for custom RPC endpoints, environment variables, and runtime settings.

```yaml
networkOverrides:
  - chain: '2390'
    host: "https://rpc.custom-chain.io"

  - chain: '8453'           # Base
    host: "https://base-rpc.example.com"

# Environment variables (available at runtime)
variables:
  - key: API_KEY
    value: "your-api-key"
    isSecret: true

  - key: DEBUG_MODE
    value: "false"
    isSecret: false

# Runtime settings
debug: false
numWorkers: 1               # Parallel workers (increase for heavy compute)
```

--------------------------------

### Configure Lending Protocol Constants

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/position-tracking-templates.md

TypeScript configuration for network and token addresses used in lending protocol tracking.

```typescript
import { EthChainId } from "@sentio/sdk/eth";
export const NETWORK = EthChainId.ETHEREUM;
export const ATOKEN = "0x...";      // aToken address (supply receipt)
export const DEBT_TOKEN = "0x...";  // variable debt token address
export const TOKEN_DECIMALS = 8;
export const DAILY_POINTS = 1000;
export const MULTIPLIER = 3;
```

--------------------------------

### Configure Token Tracking Constants

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/references/position-tracking-templates.md

Configuration file defining network, token address, and point calculation parameters.

```typescript
import { EthChainId } from "@sentio/sdk/eth";
export const NETWORK = EthChainId.ETHEREUM;
export const TOKEN_ADDRESS = "0x...";
export const TOKEN_DECIMALS = 18;
export const DAILY_POINTS = 1000;
export const MULTIPLIER = 1;
```

--------------------------------

### Initialize and Register Metrics for Sui DEX Processor

Source: https://context7.com/sentioxyz/sentio-ai-kit/llms.txt

Sets up necessary imports, defines custom types, and registers metrics like swap volume and pools created. This code should be placed at the top of your processor file.

```typescript
import { SuiNetwork, SuiObjectTypeProcessor } from "@sentio/sdk/sui"
import { pool, factory } from "./types/sui/cetus.js"
import { getPriceByType } from "@sentio/sdk/utils"
import { Gauge, Counter } from "@sentio/sdk"

const swapVolume = Gauge.register("swap_volume", { sparse: true })
const poolsCreated = Counter.register("pools_created")

interface PoolInfo {
  pairName: string
  type_a: string
  type_b: string
  decimal_a: number
  decimal_b: number
}

// Pool info cache
let poolInfoCache = new Map<string, Promise<PoolInfo>>()
```

--------------------------------

### Configure sentio.yaml

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-processor/SKILL.md

Defines project metadata, network connections, contract addresses, and runtime variables.

```yaml
project: owner/project-name     # Required
host: prod                       # prod | test | staging | local

contracts:
  - chain: "1"                   # EVM: numeric IDs ("1", "56", "137", "42161")
    address: "0x..."
    name: "USDC"
  - chain: aptos_mainnet         # Move: aptos_mainnet, sui_mainnet, iota_mainnet
    address: "0x1"
  - chain: sui_mainnet
    address: "0xdee9..."
    name: "deepbook"

networkOverrides:                # Redirect chain ID to custom RPC
  - chain: '2390'
    host: "https://rpc.tac.build"

variables:                       # Runtime env vars
  - key: API_KEY
    value: xxx
    isSecret: true

debug: false
numWorkers: 1
```

--------------------------------

### Authentication

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands to check login status or authenticate with an API key.

```bash
npx @sentio/cli@latest login --status
```

```bash
npx @sentio/cli@latest login --api-key <key>
```

--------------------------------

### Retrieve Price Data

Source: https://github.com/sentioxyz/sentio-ai-kit/blob/main/skills/sentio-platform/SKILL.md

Commands for fetching current, historical, and batch price information.

```bash
sentio price get --coin ETH
```

```bash
sentio price get --coin ETH --timestamp <unix-ts>
```

```bash
sentio price batch --file prices.yaml
```

```bash
sentio price coins
```

```bash
sentio price check-latest
```