Quickstart

You need an API key. If you don't have one yet, make one at bonkverse.io/developers; it takes a minute.

1. Keep your key out of your code

Put the key in an environment variable, not in a file you commit and never in code that runs in someone's browser.

export BONKVERSE_API_KEY="paste your key here"

2. Check the key works

curl

curl https://bonkverse.io/api/v1/me/ \
  -H "Authorization: Bearer $BONKVERSE_API_KEY"

JavaScript

// Node 18+ (fetch is built in)
const res = await fetch("https://bonkverse.io/api/v1/me/", {
  headers: { Authorization: `Bearer ${process.env.BONKVERSE_API_KEY}` },
});
console.log(await res.json());

Python

import os
import requests

res = requests.get(
    "https://bonkverse.io/api/v1/me/",
    headers={"Authorization": f"Bearer {os.environ['BONKVERSE_API_KEY']}"},
    timeout=10,
)
print(res.json())

You should get your key's name back:

{
  "ok": true,
  "data": {
    "name": "Your site",
    "prefix": "bvk_ab12cd34",
    "tier": "standard",
    "created_at": "2026-11-08T22:10:00+00:00"
  }
}

A 401 means the key is missing or wrong: see authentication.

3. Look up a player

curl

curl https://bonkverse.io/api/v1/players/comet/ \
  -H "Authorization: Bearer $BONKVERSE_API_KEY"

JavaScript

const name = "comet";
const res = await fetch(
  `https://bonkverse.io/api/v1/players/${encodeURIComponent(name)}/`,
  { headers: { Authorization: `Bearer ${process.env.BONKVERSE_API_KEY}` } },
);
const body = await res.json();
if (body.ok) console.log(body.data.username, body.data.level?.value);
else console.log("error:", body.error);

Python

from urllib.parse import quote

name = "comet"
res = requests.get(
    f"https://bonkverse.io/api/v1/players/{quote(name, safe='')}/",
    headers={"Authorization": f"Bearer {os.environ['BONKVERSE_API_KEY']}"},
    timeout=10,
)
body = res.json()
if body["ok"]:
    print(body["data"]["username"], (body["data"]["level"] or {}).get("value"))
else:
    print("error:", body["error"])

{
  "ok": true,
  "data": {
    "requested": "comet",
    "username": "Comet",
    "status": "found",
    "level": {
      "value": 87,
      "peak": 87,
      "seen_at": "2026-11-08T03:00:00.000Z",
      "seen_day": "2026-11-08",
      "estimated": false,
      "source": "replays",
      "replay": { "cycle": 6, "id": "344124" }
    },
    "games": 120,
    "account": { "dbid": 9876543, "joined": "2019-06-02", "joined_estimated": true },
    "bonkverse_account": true,
    "profile_url": "https://bonkverse.io/player/Comet/"
  }
}

Next

• Looking up lots of players? Use bulk lookup: one request for up to 250.
• Showing levels on your site? Read what "last seen" means.