papertrade-api.

01 / Overview

Execution, without the strategy.

papertrade-api is an independent, open-source integration with papertrade.xyz, a synthetic perpetuals protocol on Hyperliquid’s HyperEVM. It exposes a bearer-token-protected API for callers such as trading bots and research tools. It contains no trading strategy.

Stack

TypeScript · Node.js 24 · Hono · viem

Source

romme86/papertrade-api ↗

API base URL

https://papertrade-api.euncasino.com

02 / Quick start

Make your first request.

The hosted instance is for authorized clients. Obtain its bearer token from the operator and set API_TOKEN in your shell. Keep it on the server; do not embed it in browser code or commit it.

Check service health

/health needs no token. It reports the current mode and wallet-stream freshness. A successful liveness response alone does not mean that upstream data is ready.

curl --fail-with-body \
  https://papertrade-api.euncasino.com/health

Read market data

export API_BASE=https://papertrade-api.euncasino.com

curl --fail-with-body \
  -H "Authorization: Bearer $API_TOKEN" \
  "$API_BASE/v1/markets"

Preview an order

This request explicitly uses dryRun: true, even if the server later enables live trading. The amounts below demonstrate the request format. Review violations; a preview can return HTTP 200 while reporting unmet account or risk requirements.

curl --fail-with-body \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$API_BASE/v1/orders/open" \
  -d '{
    "market": "BTC",
    "side": "long",
    "marginUsd": "100",
    "leverage": 100,
    "dryRun": true
  }'

Successful previews return mode: "dry-run" and submission: null. Amounts should be USD strings; raw 18-decimal values in responses are strings to preserve precision.

03 / API reference

One service. A small surface.

Every /v1 route requires Authorization: Bearer <token>. Route details below reflect the repository at commit af5d474.

Responses to handle

Live opens and closes return 202; poll the intent or positions endpoint. Handle 400 for invalid requests, 401 for missing or invalid tokens, 422 for rejected risk checks, 429 for upstream rate limits, 502 for upstream errors and 503 when the wallet snapshot has not arrived. Error bodies contain an error object with code and message.

04 / Controls & limits

Checks before submission.

The wallet key signs session registrations. A separate session key signs trades and cannot withdraw funds through this service. Writes are serialized, nonces and state persist, and live submissions are recorded in an audit log.

• LIVE_TRADING=false makes trade operations previews. A client can request a dry-run but cannot force live mode.
• Open-order guards check margin, leverage, total exposure, position count, daily realized loss, snapshot freshness and session validity.
• The persistent kill switch blocks new opens while allowing closes.
• Session registration is an explicit signed write and is not protected by the trade dry-run setting. Changing the kill switch also writes local state.

Default operator limits

These are software defaults, not recommended trading parameters. The upstream protocol applies additional constraints; inspect /v1/markets before constructing an order.

05 / Self-hosting

Run your own instance.

Use Docker Compose or Node.js 24+. The repository contains the service, tests, Dockerfile, an environment example and VM provisioning scripts.

git clone https://github.com/romme86/papertrade-api.git
cd papertrade-api
cp .env.example .env
chmod 600 .env
docker compose --env-file .env build

Generate a dedicated wallet and token privately on your deployment machine. The key generator prints secrets: run it only in a private terminal and store the values in .env.

docker compose --env-file .env run --rm --no-deps \
  papertrade-api node dist/keygen.js

Set WALLET_PRIVATE_KEY and a strong API_TOKEN of at least 32 characters. Keep LIVE_TRADING=false, then start the service:

docker compose --env-file .env up -d
curl --fail-with-body http://127.0.0.1:8787/health

The repository’s Compose file binds to loopback by default. For remote access, use a private network or a TLS reverse proxy. Preserve the data volume: it contains session keys, nonce counters and the audit log. See the repository’s operator checklist for the separate, manual steps required to enable live trading.

06 / Limitations

An evolving integration.

This is an independent integration, not an official Papertrade API. It mirrors the frontend’s signed-intent protocol, which is undocumented and may change. Build-ID discovery refreshes periodically, but upstream compatibility still needs verification.

• Currently supports BTC and ETH. Positions cannot be resized; close and reopen instead.
• Withdrawals are not implemented.
• Recent closed positions and intent outcomes reflect what the running stream has observed; use history for broader records.
• Winning profits may be queued by the upstream LP. Liquidation can consume the full position margin.

Documentation reviewed on 11 October 2026 against source commit af5d474. The source and authenticated API responses are the reference for current behavior.