# PerpNow: agent reference

> PerpNow is a public testnet of a Layer 1 for perpetual futures. There is no off-chain matching engine: orders, cancels, fills, funding and liquidations are all transactions in blocks finalized by BFT consensus. The API is Hyperliquid-compatible, so most Hyperliquid SDK code only needs a new base URL. Test funds only, no real value.

## Endpoints

| Purpose | Endpoint |
|---|---|
| Market and account queries | `POST https://perpnow.xyz/info` |
| Signed trading actions | `POST https://perpnow.xyz/exchange` |
| Live streams | `wss://perpnow.xyz/ws` |
| Blocks, transactions, addresses | `POST https://perpnow.xyz/explorer` |
| Points and referrals | `POST https://perpnow.xyz/points` |
| Test USDC | `POST https://perpnow.xyz/faucet` with body `{"user": "0x..."}` |

Every request body is JSON (`content-type: application/json`).

### /info types

`meta`, `metaAndAssetCtxs`, `allMids`, `l2Book`, `candleSnapshot`, `recentTrades`, `clearinghouseState`, `openOrders`, `frontendOpenOrders`, `orderStatus`, `historicalOrders`, `userFills`, `userFunding`, `fundingHistory`, `userNonFundingLedgerUpdates`, `portfolio`, `activeAssetData`, `userRateLimit`, `subAccounts`, `vaultDetails`, `vaultSummaries`, `userVaultEquities`, `validatorOracles`.

Both `openOrders` and `frontendOpenOrders` include trigger orders, including TP/SL orders. `frontendOpenOrders` also provides frontend-specific trigger metadata.

```
curl -s https://perpnow.xyz/info -H 'content-type: application/json' -d '{"type":"meta"}'
curl -s https://perpnow.xyz/info -H 'content-type: application/json' -d '{"type":"l2Book","coin":"BTC"}'
curl -s https://perpnow.xyz/info -H 'content-type: application/json' -d '{"type":"clearinghouseState","user":"0xYourAddress"}'
```

`l2Book` accepts an optional `nSigFigs` (2–5) to group price levels. With `nSigFigs: 5`, an optional `mantissa` (1, 2 or 5) sets the bucket step. Omit both, or pass null, for the ungrouped book. The response returns up to 20 levels per side.

### /exchange actions

`order` (including TP/SL trigger groupings), `cancel`, `cancelByCloid`, `modify`, `batchModify`, `updateLeverage`, `updateIsolatedMargin`, `approveAgent`.

Order price and size formatting:

- Decimal prices allow at most 5 significant figures and at most `6 - szDecimals` fractional digits. Integer prices are always allowed.
- Sizes allow at most `szDecimals` fractional digits.
- Prices and sizes must not have trailing fractional zeroes.

### /explorer requests

Supported `type` values: `chainStats`, `recentBlocks`, `recentTxs`, `recentLiquidations`, `userRateLimit`, `userTwapSliceFills`, `twapHistory`, `blockDetails`, `txDetails`, `orderDetails`, `userDetails`, `blockCertificate`, `pointsDay`.

```json
{"type":"blockDetails","height":123}
```

### /points requests

Supported `type` values: `season`, `leaderboard`, `user`, `code`, `bind`. Leaderboards accept `board` values `points`, `roi`, or `volume`.

```json
{"type":"leaderboard","board":"points","limit":20}
```

### WebSocket subscriptions

`allMids`, `l2Book`, `trades`, `candle`, `activeAssetCtx`, `userFills`, `explorerBlock`, `explorerTxs`.

```
{ "method": "subscribe", "subscription": { "type": "l2Book", "coin": "BTC" } }
{ "method": "subscribe", "subscription": { "type": "trades", "coin": "ETH" } }
{ "method": "subscribe", "subscription": { "type": "userFills", "user": "0xYourAddress" } }
```

Updates are pushed as soon as they are committed, so there is no need to poll.

## Signing

- EIP-712 signatures are identical to Hyperliquid's, checked against 92 reference vectors.
- `approveAgent` and other user-signed actions use the EIP-712 domain `HyperliquidSignTransaction`, chainId `421614` (`0x66eee`). The action must include `signatureChainId: "0x66eee"` and `hyperliquidChain: "Testnet"`. The official SDK's `approve_agent` supplies these fields.
- L1 actions use the Exchange / phantom-agent signing domain. With the official Hyperliquid Python SDK, pass `base_url="https://perpnow.xyz"` and use testnet settings (`is_mainnet = false`).
- The nonce is the millisecond timestamp. Each nonce works once per signer, which prevents replay.
- Trade with an agent (API wallet) key that your main wallet approves via `approveAgent`.

```python
from hyperliquid.info import Info
info = Info("https://perpnow.xyz", skip_ws=True)
print(info.l2_snapshot("BTC"))
```

```json
{
  "type":"approveAgent",
  "hyperliquidChain":"Testnet",
  "signatureChainId":"0x66eee",
  "agentAddress":"0x...",
  "agentName":"my-agent",
  "nonce":1730000000000
}
```

## Markets

PerpNow offers 195 USD-quoted perpetual markets (175 crypto + 20 TradFi) across crypto, stocks and commodities. Use `{"type":"meta"}` for the live list.

Selected market examples (not the complete live list):

| Market | Size decimals | Max leverage |
|---|---:|---:|
| BTC | 5 | 40x |
| ETH | 4 | 25x |
| SOL | 2 | 20x |
| XRP | 0 | 20x |
| BNB | 3 | 10x |
| DOGE | 0 | 10x |
| ADA | 0 | 10x |
| AVAX | 2 | 10x |
| LINK | 1 | 10x |
| LTC | 2 | 10x |
| SUI | 1 | 10x |
| NEAR | 1 | 10x |
| HYPE | 2 | 10x |
| ZEC | 2 | 10x |
| ENA | 0 | 10x |
| UNI | 1 | 10x |
| WLD | 1 | 10x |
| ONDO | 0 | 10x |
| TAO | 3 | 5x |
| AAVE | 2 | 10x |
| CRV | 1 | 10x |
| ARB | 1 | 10x |
| JUP | 0 | 10x |
| STRK | 1 | 5x |
| ZRO | 1 | 5x |
| TRX | 0 | 10x |
| DOT | 1 | 10x |
| APT | 2 | 10x |
| OP | 1 | 5x |
| BCH | 3 | 10x |
| ATOM | 2 | 5x |
| DYDX | 1 | 5x |
| APE | 1 | 5x |
| INJ | 1 | 5x |
| kPEPE | 0 | 10x |
| LDO | 1 | 5x |
| STX | 1 | 5x |
| CFX | 0 | 5x |
| GMX | 2 | 3x |
| SNX | 1 | 3x |
| COMP | 2 | 5x |
| YGG | 0 | 3x |
| kSHIB | 0 | 10x |
| SEI | 0 | 5x |
| RUNE | 1 | 5x |
| BANANA | 1 | 3x |
| TRB | 2 | 3x |
| BIGTIME | 0 | 3x |
| KAS | 0 | 3x |
| BLUR | 0 | 3x |
| TIA | 1 | 5x |
| BSV | 2 | 3x |
| MINA | 0 | 3x |
| POLYX | 0 | 3x |
| GAS | 1 | 3x |
| PENDLE | 0 | 5x |
| FET | 0 | 5x |
| MEME | 0 | 3x |
| ORDI | 2 | 3x |
| NEO | 2 | 5x |
| ZEN | 2 | 5x |
| FIL | 1 | 5x |
| PYTH | 0 | 5x |
| SUSHI | 1 | 3x |
| IMX | 1 | 5x |
| kBONK | 0 | 10x |
| GMT | 0 | 3x |
| SUPER | 0 | 3x |
| kLUNC | 0 | 3x |
| RSR | 0 | 3x |
| GALA | 0 | 3x |
| JTO | 0 | 5x |
| ACE | 2 | 3x |
| WIF | 0 | 5x |
| CAKE | 1 | 3x |
| PEOPLE | 0 | 3x |
| ENS | 2 | 5x |
| ETC | 2 | 5x |
| XAI | 1 | 3x |
| MANTA | 1 | 3x |
| UMA | 1 | 3x |
| ALT | 0 | 3x |
| ZETA | 1 | 3x |
| DYM | 1 | 3x |
| W | 1 | 5x |
| AR | 2 | 5x |
| kFLOKI | 0 | 5x |
| BOME | 0 | 3x |
| ETHFI | 1 | 5x |
| TNSR | 1 | 3x |
| SAGA | 1 | 3x |
| MERL | 0 | 3x |
| HBAR | 0 | 5x |
| POPCAT | 0 | 3x |
| EIGEN | 2 | 5x |
| REZ | 0 | 3x |
| NOT | 0 | 3x |
| TURBO | 0 | 3x |
| BRETT | 0 | 3x |
| IO | 1 | 3x |
| ZK | 0 | 5x |
| RENDER | 1 | 5x |
| POL | 0 | 5x |
| CELO | 0 | 3x |
| HMSTR | 0 | 3x |
| kNEIRO | 1 | 3x |
| GOAT | 0 | 3x |
| MOODENG | 0 | 3x |
| GRASS | 1 | 3x |
| PNUT | 1 | 3x |
| XLM | 0 | 5x |
| SAND | 0 | 5x |
| IOTA | 0 | 3x |
| ALGO | 0 | 5x |
| ME | 1 | 3x |
| MOVE | 0 | 3x |
| VIRTUAL | 1 | 5x |
| PENGU | 0 | 5x |
| USUAL | 1 | 3x |
| FARTCOIN | 1 | 10x |
| AIXBT | 0 | 3x |
| BIO | 0 | 3x |
| GRIFFAIN | 0 | 3x |
| SPX | 1 | 5x |
| S | 0 | 5x |
| MORPHO | 1 | 5x |
| TRUMP | 1 | 10x |
| MELANIA | 1 | 3x |
| ANIME | 0 | 3x |
| VVV | 2 | 3x |
| BERA | 1 | 5x |
| LAYER | 0 | 3x |
| KAITO | 0 | 5x |
| NIL | 0 | 3x |
| PAXG | 3 | 10x |
| BABY | 0 | 3x |
| WCT | 0 | 3x |
| HYPER | 0 | 3x |
| ZORA | 0 | 3x |
| INIT | 0 | 3x |
| NXPC | 0 | 3x |
| SOPH | 0 | 3x |
| RESOLV | 0 | 3x |
| SYRUP | 0 | 3x |
| PUMP | 0 | 10x |
| PROVE | 0 | 3x |
| XPL | 0 | 10x |
| WLFI | 0 | 5x |
| LINEA | 0 | 3x |
| SKY | 0 | 3x |
| ASTER | 0 | 5x |
| AVNT | 0 | 5x |
| STBL | 0 | 3x |
| 0G | 0 | 3x |
| HEMI | 0 | 3x |
| 2Z | 0 | 3x |
| MON | 0 | 5x |
| MET | 0 | 3x |
| MEGA | 0 | 3x |
| CC | 0 | 3x |
| ICP | 1 | 5x |
| AERO | 0 | 3x |
| STABLE | 0 | 3x |
| FOGO | 0 | 3x |
| LIT | 0 | 5x |
| XMR | 3 | 5x |
| AXS | 1 | 5x |
| DASH | 2 | 5x |
| SKR | 0 | 3x |
| AZTEC | 0 | 3x |
| CHIP | 0 | 3x |
| GRAM | 0 | 5x |
| CASHCAT | 0 | 3x |
| PONS | 0 | 3x |
| USELESS | 0 | 3x |

## Orders and fees

- Time in force: GTC (rests whatever does not match), IOC (cancels whatever does not fill), ALO (post-only: rejected if it would match immediately). A market order is an IOC limit with a slippage price.
- Reduce-only orders can only shrink a position and are clipped to its size.
- Matching uses price-time priority, and fills happen at the maker's price. On a self-trade, the resting order is cancelled.
- An account can have at most 1,000 open orders. Client order ids (`cloid`) are supported.
- TP/SL triggers execute on-chain from the mark price. Market triggers use an IOC limit with 10% slippage protection.
- Fees: taker 0.045%, maker 0.015%. Example: a $10,000 market buy pays $4.50.

## Margin

- Cross margin: all cross positions share the account balance. Isolated margin: each position has its own margin.
- Initial margin = position value ÷ leverage. Maintenance margin = position value ÷ (2 × max leverage).
- Example: a $10,000 BTC long at 40x has $250 of margin and $125 of maintenance. A 1.25% drop leaves $125 of equity, and liquidation starts.
- After removing margin, at least max(initial margin, 10% of position value) must remain, including unrealized PnL.

## Mark price, funding, liquidation

- Mark price = median of: oracle + 150 s EMA of (book mid − oracle); the median of best bid, best ask and last trade; the CEX perp price. Each validator signs its own oracle prices every 3 s, and the chain uses the stake-weighted median.
- Funding is paid every hour; when the rate is positive, longs pay shorts. Hourly rate = (average premium + clamp(0.01% − average premium, ±0.05%)) ÷ 8, capped at 4% per hour.
- Liquidation: when equity falls below maintenance margin, the chain sends reduce-only IOC orders. Positions over $100K are reduced 20% at a time. Below ⅔ of maintenance margin, the backstop vault takes the position at mark. If the vault cannot absorb it, auto-deleveraging closes the most profitable, most leveraged opposite positions.

## Rate limits (per client IP)

- HTTP: 1,200 weight per minute, refilling at 20 per second.
  - `/exchange` costs 1 + floor(orders / 40).
  - These `/info` types cost 2: `l2Book`, `allMids`, `clearinghouseState`, `orderStatus`, `spotClearinghouseState`, `exchangeStatus`, `activeAssetData`, `meta`, `metaAndAssetCtxs`, `openOrders`, `frontendOpenOrders`, `userRateLimit`.
  - Other `/info` types, `/explorer`, `/points` and `/faucet` cost 20.
- Over the limit, the response is HTTP 429 with a `Retry-After` header and `{"status":"err","response":"rate limited, retry in Ns"}`.
- WebSocket: at most 10 concurrent connections per IP, and at most 30 new connections per minute. Prefer one connection with many subscriptions.

## Faucet

`POST /faucet` with `{"user":"0xYourAddress"}` deposits 10,000 test USDC. Limits: one claim per address per 24 h, at most 10 claims per IP per 24 h, and 2,000 claims per day network-wide. A refused claim returns HTTP 429 with `nextAllowedAt`.