DEV Community

Bitnxs
Bitnxs

Posted on

Run perp market checks with the open-source Bitnxs Grok Bot template

Written by the Bitnxs team. We build Bitnxs, a DEX for USDC-margined perpetual futures, and we maintain the template covered here.

We open-sourced a Grok Bot template for Bitnxs under the MIT license. It's small on purpose: three skill files and two Python scripts. This post walks through what's in it, how to run the market checks locally, and how the agent side fits together. Everything below was run against the live API while writing.

Quick context if you haven't seen Bitnxs: it lists USDC-margined perpetuals on BTC, ETH and SOL. Max leverage is 50x on BTC and ETH and 20x on SOL, funding is paid hourly, and fees are 0.02% maker and 0.05% taker. You can trade in the web app at www.bitnxs.com or through the API documented at docs.bitnxs.com.

Get the repo

git clone https://github.com/Bitnxs-Labs/bitnxs-grokbot
cd bitnxs-grokbot
Enter fullscreen mode Exit fullscreen mode

The layout:

LICENSE
README.md
scripts/snapshot.py
scripts/trade_min.py
skills/bitnxs-getting-started/SKILL.md
skills/bitnxs-market-brief/SKILL.md
skills/bitnxs-trading/SKILL.md
Enter fullscreen mode Exit fullscreen mode

The skills are Markdown instructions the agent reads. The scripts are what it actually runs. You can use the scripts without any agent at all, which is the easiest way to see what the bot sees.

Step 1: a read-only market snapshot

snapshot.py uses only the Python standard library and needs no API key.

python3 scripts/snapshot.py            # every listed market
python3 scripts/snapshot.py BTC ETH    # just these
python3 scripts/snapshot.py --json     # machine-readable rows
Enter fullscreen mode Exit fullscreen mode

The table has one row per coin: mark price, 24h change, funding per hour, the yearly equivalent of that funding rate, open interest, 24h volume and best bid/ask spread in basis points. The last line tells you how many minutes until the next hourly funding.

Under the hood it's a handful of POSTs to one endpoint:

BASE = "https://api.bitnxs.com"

def info(body, retries=3):
    data = json.dumps(body).encode()
    req = urllib.request.Request(f"{BASE}/info", data=data, method="POST",
                                 headers={"Content-Type": "application/json",
                                          "User-Agent": "bitnxs-snapshot/1.0"})
    ...
Enter fullscreen mode Exit fullscreen mode

The script calls meta to get the listed coins, allMids for prices, then marketSummary and l2Book per coin. Two details we learned the hard way and baked in:

  • Set a User-Agent. Python's default urllib User-Agent gets an HTTP 403. Any custom string works.
  • Check meta before asking about a coin. Unknown coins return a summary full of zeros instead of an error, so the script checks assetToId first and marks anything else as "not listed".

Funding comes back as a percent per hour. 0.0100 means 0.01% per hour, so the script multiplies by 24 × 365 to show a yearly figure. That's an annualized rate for comparison, not a forecast of anything.

Step 2: how the agent uses it

The template has three skills.

bitnxs-getting-started runs the first conversation. It sends a live snapshot right away, then asks which coins you care about, whether you want a regular brief and when, and what alert thresholds you want (a price level, a 24h move beyond some percent, funding above or below a rate). It saves those to memory and creates one routine for the brief and one for alerts. The alert routine stays quiet when nothing crossed.

bitnxs-market-brief is read-only. It never places orders and never needs a key. It's also where we wrote down API quirks so the agent doesn't have to rediscover them. A few from the file:

  • Every public read is POST https://api.bitnxs.com/info with {"type": ...}. Without Content-Type: application/json you get HTTP 415.
  • Numbers are decimal strings, timestamps are UTC milliseconds, and errors come back as plain text, not JSON.
  • Candles need both startTime and endTime as integer milliseconds, camelCase. An unknown interval silently falls back to 5m.
  • recentTrades requires limit (max 500).
  • There's no public liquidation feed. If someone asks for liquidation levels, the skill only offers a clearly labeled estimate.

If you write your own agent for any API, this kind of file pays off. The model stops guessing parameter names, and you stop debugging the same 415.

bitnxs-trading is the part that touches an account. It covers placing, modifying and cancelling orders, changing leverage and setting TP/SL. It only works once you've created your own API key under More > API Keys in the web app, and the template collects that key through a masked secret field, not in chat.

To try it, the README has an "Import Bitnxs Bot" button for Grok Bot. Importing starts the getting-started conversation.

Step 3: the trading script, without sending anything

trade_min.py is the minimal trading client the trading skill relies on. It needs one dependency:

python3 -m venv .venv
.venv/bin/pip install "eth-account>=0.13"
.venv/bin/python scripts/trade_min.py selftest
Enter fullscreen mode Exit fullscreen mode

selftest runs offline. It signs a sample challenge with a throwaway key, recovers the address and checks decimal formatting. You should see selftest ok.

The subcommands are account, place, cancel, cancel-all, leverage, tpsl, cancel-trigger and selftest. For real use it reads BITNXS_API_KEY and BITNXS_USER (your main wallet address) from the environment. The global flags go before the subcommand:

export BITNXS_USER=0xYourMainWallet
export BITNXS_API_KEY=0xYourApiKey
.venv/bin/python scripts/trade_min.py --dry-run place BTC buy 0.001 --price 50000
Enter fullscreen mode Exit fullscreen mode

With --dry-run the script prints the order body it would send to /session/order and stops there:

{
 "POST /session/order": {
  "sessionId": "<sessionId>",
  "asset": 1,
  "isBuy": true,
  "limitPx": "50000",
  "sz": "0.001",
  "reduceOnly": false,
  "orderType": {"type": "limit", "tif": "Gtc"}
 }
}
Enter fullscreen mode Exit fullscreen mode

Without --dry-run or --yes, any write command exits with live request: add --yes or --dry-run. That guard exists because there is no testnet. Anything sent with --yes is a real order on a real account.

How auth works, briefly: the API key is a delegate signing key derived from your wallet. The client calls /session/start, signs the returned challenge with the key (raw keccak, not personal_sign), sends it to /session/complete, and gets a sessionId for the order calls. There are no bearer tokens or HMAC secrets. The API overview has the full flow in Python, and the script revokes its session when it's done.

Step 4: wire it into your own agent

You don't need Grok Bot to reuse any of this. The pattern is portable:

  1. Give the model a read-only tool that returns the snapshot JSON (snapshot.py --json).
  2. Put the API rules in the system prompt or a skill file, like bitnxs-market-brief does.
  3. Keep anything that writes to an account behind a separate tool with a dry-run path, and keep scheduled routines read-only. The template's routines never place trades.

Bitnxs also has its own experimental agent panel in the web app at bitnxs.com/#/agent, which works with any OpenAI-compatible endpoint. The AI Agent docs cover what it can and can't do. It's a different thing from this template, but the same idea.

Before you trade

Perpetual futures with leverage can lose your entire margin, quickly. An agent doesn't change that, and a confident-sounding model is not evidence of a good trade. Nothing here is investment advice, and we don't promise any result from using the template. Bitnxs is not available in restricted regions, including the United States, Canada, the United Kingdom and Mainland China; the full list is in the Terms. Withdrawals go through a review of about 5 minutes and may be held or rejected.

Issues and pull requests are welcome on GitHub. If you want to look at the markets first, www.bitnxs.com has the trading page.

Top comments (0)