Overlay Market

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

External Services

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]

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)

Resources

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