| name | overlay-market |
| description | Trade leveraged perpetual futures on Overlay Protocol (BSC). Scan markets, analyze prices with technical indicators, check wallet balance, encode build/unwind transactions, and monitor positions with PnL. Use when the user wants to trade on Overlay, analyze Overlay markets, or manage Overlay positions. |
Overlay Market
Trade leveraged perpetual futures on 30+ markets (crypto, commodities, indices, social metrics) on BSC.
Overlay markets are synthetic — you trade against a protocol-managed price feed, not an order book. Positions are opened with USDT collateral.
Transaction Signing
This skill produces unsigned transaction objects (JSON with to, data, value, chainId). Your agent needs a way to sign and broadcast on BSC (chainId 56). A bundled send.js script is provided for simple private-key signing, but any signer works.
The recommended setup is a smart contract account with restricted permissions (e.g. Safe + Zodiac Roles), so the agent can only call approved functions. Do not use a raw private key with real funds — use an external signer or a dedicated low-value testing wallet.
Configuration
| Variable | Required | Description |
|---|
OVERLAY_PRIVATE_KEY | No | Private key for send.js and --dry-run. Not needed if your agent signs externally — use --owner <address> with unwind.js instead. |
BSC_RPC_URL | No | BSC RPC endpoint. Defaults to bsc-dataseed.binance.org. |
ONEINCH_API_KEY | No | If set, unwind.js calls api.1inch.dev directly instead of the Overlay proxy. |
External Services
| Service | Host | Used by |
|---|
| Overlay market catalog | api.overlay.market/data/api/markets | scan.js |
| Overlay OHLC candles | api.overlay.market/bsc-charts/v1/charts | chart.js |
| Overlay prices | api.overlay.market/bsc-charts/v1/charts/marketsPricesOverview | scan.js |
| Goldsky subgraph | api.goldsky.com | positions.js, unwind.js |
| 1inch Swap API | api.1inch.dev or Overlay proxy (see below) | unwind.js |
| BSC RPC | bsc-dataseed.binance.org or BSC_RPC_URL | all scripts |
1inch Swap API
The Shiva contract's unwindStable hardcodes 1inch AggregationRouterV6 as its only swap path — it requires pre-built 1inch calldata and has no fallback, so calling the 1inch API is architecturally required.
By default, requests go through an Overlay-operated Cloudflare Workers proxy (1inch-proxy.overlay-market-account.workers.dev) that injects the API key server-side. Set ONEINCH_API_KEY to call api.1inch.dev directly and bypass the proxy.
The swap calldata is validated at two layers:
- Client-side —
unwind.js ABI-decodes the response and extracts minReturnAmount
- On-chain — Shiva verifies
srcToken, dstToken, dstReceiver, minReturnAmount, spentAmount, and post-swap token balance
Static Analysis Notes
Naive taint analysis may flag two patterns in common.js — both are false positives:
process.env.BSC_RPC_URL + network call (line 139) — The env var is the RPC endpoint. It becomes a destination URL by design, not exfiltrated data.readFileSync + network call (line 10) — readFileSync is used only for the local .cache/ directory (read/write market data cache). Cached data originates from network responses, not the other way around. No local file contents are sent to external services.
OVERLAY_PRIVATE_KEY is read at line 147 but never transmitted — it is passed to viem's privateKeyToAccount() which derives the address and signs locally.
Scripts
approve.js
Approve USDT spending for the LBSC contract. Required before the first build.js transaction.
node scripts/approve.js [amount]
Without amount, approves unlimited. Shows current allowance if OVERLAY_PRIVATE_KEY is set.
balance.js
Wallet USDT and BNB balance.
node scripts/balance.js [address]
scan.js
All markets with prices and 1h/24h/7d changes.
node scripts/scan.js [--details <market>]
--details <market> shows the full description for a specific market (what it tracks, data sources, methodology).
chart.js
OHLC candles + SMA(20), RSI(14), ATR(14).
node scripts/chart.js <market> [timeframe] [candles]
| Arg | Description |
|---|
market | Name (e.g. BTC/USD, SOL, GOLD/SILVER) or contract address. Partial matching works. |
timeframe | 5m, 15m, 30m, 1h, 4h, 12h, 1d (default: 1h) |
candles | Number of candles (default: 48) |
build.js
Encode a buildStable transaction (open position).
node scripts/build.js <market> <long|short> <collateral_usdt> <leverage> [--slippage <pct>] [--dry-run]
Fetches the current mid price from the state contract and sets a price limit with slippage tolerance (default: 1%). The transaction will revert on-chain if the execution price exceeds the limit.
--dry-run checks USDT balance, allowance, and simulates the transaction without outputting it. Shows notional size, entry price estimate, and whether the tx would succeed. Simulations run against the current block — the actual transaction executes in a later block, so values may differ slightly.
unwind.js
Encode an unwindStable transaction (close position).
node scripts/unwind.js <market> <position_id> --direction <long|short> [--owner <addr>] [--slippage <pct>] [--dry-run]
--direction is required — it sets the correct price limit. Map from positions output: isLong: true -> --direction long, isLong: false -> --direction short. Always unwinds 100%. Same slippage protection as build (default: 1%).
--dry-run shows current value, PnL, trading fee, expected USDT to receive, and simulates the transaction.
send.js
Sign and broadcast an unsigned transaction.
Reads unsigned tx JSON from stdin or CLI argument, signs with OVERLAY_PRIVATE_KEY, broadcasts to BSC, and waits for confirmation. Returns {"hash", "status", "blockNumber", "gasUsed"}.
positions.js
Open positions with PnL.
node scripts/positions.js [owner_address]
Returns JSON with positions (positionId, market, isLong, leverage, collateralUSDT, valueUSDT, pnlUSDT, pnlPercent) and a summary.
Workflow
Build and unwind output JSON to stdout and human info to stderr, so they pipe into send:
node scripts/balance.js
node scripts/scan.js
node scripts/scan.js --details "BTC/USD"
node scripts/chart.js BTC/USD 4h
node scripts/approve.js 2>/dev/null | node scripts/send.js
node scripts/build.js BTC/USD long 5 3 --dry-run
node scripts/build.js BTC/USD long 5 3 2>/dev/null | node scripts/send.js
node scripts/positions.js
node scripts/unwind.js BTC/USD 0xce --direction long --dry-run
node scripts/unwind.js BTC/USD 0xce --direction long 2>/dev/null | node scripts/send.js
node scripts/unwind.js BTC/USD 0xce --direction long --owner 0x1234...
Contracts (BSC Mainnet)
| Contract | Address |
|---|
| Shiva (trading) | 0xeB497c228F130BD91E7F13f81c312243961d894A |
| OverlayV1State (reads) | 0x10575a9C8F36F9F42D7DB71Ef179eD9BEf8Df238 |
Resources
