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

| 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:

```bash
# 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