overlay-market

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:

# Research
node scripts/balance.js
node scripts/scan.js
node scripts/scan.js --details "BTC/USD"
node scripts/chart.js BTC/USD 4h

# Approve USDT (once, before first trade)
node scripts/approve.js 2>/dev/null | node scripts/send.js

# Dry-run before opening
node scripts/build.js BTC/USD long 5 3 --dry-run

# Open: 5 USDT long BTC 3x
node scripts/build.js BTC/USD long 5 3 2>/dev/null | node scripts/send.js

# Monitor
node scripts/positions.js

# Dry-run before closing
node scripts/unwind.js BTC/USD 0xce --direction long --dry-run

# Close (positionId and direction from positions output)
node scripts/unwind.js BTC/USD 0xce --direction long 2>/dev/null | node scripts/send.js

# Without OVERLAY_PRIVATE_KEY (external signer)
node scripts/unwind.js BTC/USD 0xce --direction long --owner 0x1234...

Contracts (BSC Mainnet)

Contract	Address
Shiva (trading)	0xeB497c228F130BD91E7F13f81c312243961d894A
OverlayV1State (reads)	0x10575a9C8F36F9F42D7DB71Ef179eD9BEf8Df238

Resources

• App: https://app.overlay.market
• Docs: https://docs.overlay.market