Skills overlay-market

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.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/arthurka-o/overlay-market" ~/.claude/skills/clawdbot-skills-overlay-market && rm -rf "$T"

manifest: skills/arthurka-o/overlay-market/SKILL.md

source content

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

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

BSC RPC endpoint. Defaults to

bsc-dataseed.binance.org

ONEINCH_API_KEY

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:

)

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