krapio

App API

Login with Krunker, OAuth 2.0 and the API a player lets an app use

Base URL: https://gapi.svc.krunker.io/app/v1

This is the Login with Krunker documentation as provided by Krunker (FRVR) in November 2026, rearranged to the layout of the other pages. Notes marked observed were found by calling the service without credentials in November 2026: the discovery document, the refusal of the token endpoint and the refusal of the app API. Everything else is reproduced as documented and not verified, no app was registered to check it with.

Login with Krunker lets players sign in to a website, bot or tool with their Krunker account. With their consent, an app can also read their game data (stats, inventory, trades, friends, ...) and act for them (list on the market, trade, send KR, follow players, send DMs).

It is standard OAuth 2.0: the authorization code flow with PKCE (S256), refresh tokens with rotation, token revocation (RFC 7009), a discovery document (RFC 8414) and a small userinfo endpoint. Implicit flow, password grant and client credentials are not offered.

URL
API basehttps://gapi.svc.krunker.io
App APIhttps://gapi.svc.krunker.io/app/v1
Discoveryhttps://gapi.svc.krunker.io/.well-known/oauth-authorization-server
Consent pagehttps://krunker.io/oauth/authorize

In krapio the flow lives on krunker.oauth and the reads on krunker.app(accessToken).*. Every write of the app API (market, trades, items, KR, follows, DMs) is documented below and left out of the library on purpose, like the writes of the other tiers; their body and reply types are exported anyway.

import { Krunker, createPkce, createState, parseCallback } from "krapio";

const krunker = new Krunker({ app: { clientId: "kapp_...", clientSecret: "kas_...", redirectUri: "https://example.com/callback" } });

// 1. send the player to the consent page; keep verifier and state in their session
const pkce = await createPkce();
const state = createState();
const url = krunker.oauth.authorizeUrl({ scope: ["profile", "stats:read"], state, codeChallenge: pkce.challenge });

// 2. back on the redirect uri: check the state, exchange the code
const callback = parseCallback(request.url, state);
if (callback.kind === "code"){
    const tokens = await krunker.oauth.exchangeCode({ code: callback.code, codeVerifier: pkce.verifier });

    // 3. read with the access token
    const me = krunker.app(tokens.access_token);
    const { data: player, scopes } = await me.player.me();
    const stats = await me.stats.get();
}

What players see

  • They sign in on krunker.io (the page reuses their game session) and see your app's name, icon, developer and links, and the list of scopes you asked for.
  • Their account must have 2FA enabled to connect any app. Banned accounts can't connect apps.
  • They can untick optional scopes, so your app may get fewer scopes than it asked for.
  • Write scopes are shown in a warning block with a disclaimer they must tick, and granting one asks for a fresh 2FA code.
  • Everything your app does on their account counts as their own action and is listed in their app activity. Krunker support can't recover items, KR or currency lost through a third-party app.
  • They can disconnect your app at any time in Krunker (Account > Connections > Connected apps). Its tokens stop working immediately.

Things an app can never do: spend real money or KR in the shop, spins or premium; touch account security (name, email, password, 2FA, deletion, linked accounts); report players or use moderation tools; or use items the player has locked in game.


Registering an app

Apps are managed in the partner portal under Developer > Applications. The section appears once the Krunker team has given your developer key an app quota. Creating an app requires accepting the Krunker API & App Terms.

App settings

SettingRules
Name2 to 40 characters, shown on the consent page
DescriptionUp to 300 characters
Homepage, privacy policy, terms of serviceOptional https:// URLs. A privacy policy is required before you can request a write scope
Redirect URIs1 to 10, one per line, matched exactly (no wildcards, no fragments, no credentials). https:// only, except http://localhost and http://127.0.0.1 (any port), which work only while the app is in dev mode
Client typeConfidential (a server that keeps a client secret) or public (a browser or native app with no secret, PKCE only). Public clients get read scopes only
IconSquare PNG, JPEG or WebP, 64 to 1024 px, up to 256 KB

When the terms change, you accept the new version before your next settings change. Existing tokens keep working.

Credentials

  • Client id kapp_...: public, sent in authorize and token requests.
  • Client secret kas_... (confidential apps only): shown once when you create the app or rotate it. Keep it on your server. After a rotation the previous secret keeps working for 24 hours, so you can deploy the new one.

In krapio both go into new Krunker({ app: { clientId, clientSecret, redirectUri } }), or into new KrunkerOAuth({ ... }) when the flow is all you need. Leave clientSecret out for a public client.

Scopes for your app

A new app can only use profile. Request every other scope on the app page with a short reason; the Krunker team reviews each request. Only approved scopes (plus profile) may appear in an authorize request; anything else is refused with invalid_scope.

Dev mode, testers and going live

StatusWho can authoriseNotes
Dev modeYou and up to 25 testersEvery new app starts here. Add testers by player name on the app page. Loopback redirect URIs work
LiveEvery playerAsk the Krunker team to make the app live once it is ready. Loopback redirect URIs stop working
SuspendedNobodySet by the Krunker team. Tokens are rejected and the consent page shows the app as unavailable. You can only delete it

Apps also stop working while your developer key is disabled.


Discovery

Standard OAuth client libraries can configure themselves from the discovery document:

GET https://gapi.svc.krunker.io/.well-known/oauth-authorization-server

krunker.oauth.discovery()

{
  "issuer": "https://gapi.svc.krunker.io",
  "authorization_endpoint": "https://krunker.io/oauth/authorize",
  "token_endpoint": "https://gapi.svc.krunker.io/oauth/token",
  "revocation_endpoint": "https://gapi.svc.krunker.io/oauth/revoke",
  "userinfo_endpoint": "https://gapi.svc.krunker.io/app/v1/me",
  "scopes_supported": ["profile", "stats:read", "notifications:read", "inventory:read", "inventory:write:skins", "inventory:write:currency", "inventory:write", "trades:read", "trades:write", "market:read", "market:write", "friends:read", "friends:write", "dms:read", "dms:write", "clan:read", "maps:read", "events:subscribe"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"]
}

observed: the live document is exactly this, needs no auth and lists the same 18 scopes.

Tokens are opaque strings, not JWTs, so there is no JWKS or ID token. Use GET /app/v1/me to get the player.


Signing a player in

1. Create a PKCE verifier and a state

For every sign-in attempt, generate:

  • a code verifier: 43 to 128 characters from A-Z a-z 0-9 - . _ ~ (32 random bytes, base64url-encoded, gives 43);
  • its code challenge: base64url(sha256(verifier)) without padding (43 characters);
  • a random state (required, up to 500 characters), tied to the visitor's session so you can check it on the way back.

Keep the verifier and state on your side; only the challenge and state go in the URL.

import { createPkce, createState } from "krapio";

const { verifier, challenge } = await createPkce(); // WebCrypto, so it runs in node, bun and a browser
const state = createState();

Redirect the browser to the authorization endpoint:

https://krunker.io/oauth/authorize
  ?response_type=code
  &client_id=kapp_3f9c0a1b2c3d4e5f60718293
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &scope=profile%20stats%3Aread%20inventory%3Aread
  &state=Zt3nq0H1oV8yXw2cJ5bL4g
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

krunker.oauth.authorizeUrl({ scope, state, codeChallenge, redirectUri }) builds it. Nothing is sent.

ParameterRequiredDescription
response_typeyesAlways code
client_idyesYour kapp_... id
redirect_uriyesOne of your registered redirect URIs, character for character
scopeyesSpace-separated scopes. profile is always added
stateyesYour random value, returned unchanged
code_challengeyesThe S256 challenge from step 1
code_challenge_methodyesAlways S256; plain is not supported

If the player already granted every scope you ask for, the page shows a one-click "Continue as ..." instead of the full consent screen. A new write scope always shows the full screen.

3. Handle the redirect back

When the player approves, the browser comes back to your redirect URI:

https://example.com/callback?code=x5bH1v...&state=Zt3nq0H1oV8yXw2cJ5bL4g

Check that state matches the one you stored for this visitor before doing anything else. The code is valid for 60 seconds and can be used once (a failed exchange also uses it up). It only works with your client id and the same redirect URI.

If the player declines, or the request was invalid, you get an error instead:

https://example.com/callback?error=access_denied&error_description=The+player+denied+the+request.&state=Zt3nq0H1oV8yXw2cJ5bL4g
errorMeaning
access_deniedThe player declined
invalid_requeststate is missing or too long, or PKCE is missing or not S256
invalid_scopeAn unknown scope, or one that isn't approved for your app (or is a write scope on a public client)
unsupported_response_typeresponse_type isn't code

Some problems are shown to the player on the Krunker page and never sent back to your app, because the redirect can't be trusted or the player has to fix something first: unknown client id, a redirect URI that isn't registered (or a loopback URI on a live app), an unavailable app, an app in dev mode that the player isn't a tester of, a banned account, an account without 2FA, a level too low for a scope, or a wrong 2FA code.

In krapio parseCallback(url, expectedState) does the state check first and then returns { kind: "code", code }. It throws KrunkerOAuthError when the state is not yours (error is state_mismatch) or the redirect carries an error (access_denied, ...). The same function reads the redirect of a per-action approval, as { kind: "action", actionId, status }.

4. Exchange the code for tokens

POST https://gapi.svc.krunker.io/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(urlencode(client_id) + ":" + urlencode(client_secret))

grant_type=authorization_code&code=x5bH1v...&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

krunker.oauth.exchangeCode({ code, codeVerifier, redirectUri })

How your app authenticates depends on its client type:

Client typeHow to send credentials
ConfidentialHTTP Basic with client_id:client_secret (recommended), or client_id and client_secret in the body
Publicclient_id in the body and no secret. Sending a secret fails with invalid_client

The body can also be JSON (Content-Type: application/json) with the same field names. krapio sends a form body, with HTTP Basic when it has a secret and client_id in the body when it has none.

Response (200):

{
  "access_token": "kat_Q2xh...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "krt_9mWv...",
  "scope": "profile stats:read",
  "sub": "0f29b001-eb77-4d21-885f-c121a6511df4"
}
  • scope is what the player actually granted this time. It can be a subset of what you asked for; check it rather than assuming.
  • sub is the player's subject id in your app. Use it as your user key.
  • Responses carry Cache-Control: no-store. Store tokens server-side, never in URLs or logs.

krapio returns this body as it is (OAuthTokens) and keeps none of it. It sends a token request once and never retries it, not even after a network error or a 5xx: the first attempt may have spent the code or the refresh token.


Tokens

Lifetimes

WhatLifetime
Authorization code60 seconds, single use
Access token kat_...1 hour (expires_in: 3600)
Refresh token krt_...60 days from when it was issued. Each refresh gives a new one with a fresh 60 days
Per-action approval10 minutes to approve; the result is kept 24 hours

An access token also stops working before it expires when the player disconnects your app, the player is banned, your app is suspended or your developer key is disabled. Changes made by Krunker take effect within about 15 seconds.

Refreshing

POST https://gapi.svc.krunker.io/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ...

grant_type=refresh_token&refresh_token=krt_9mWv...

krunker.oauth.refresh(refreshToken)

The response has the same shape as the code exchange, with a new access token and a new refresh token. Refresh tokens rotate:

  • Each refresh token works once. Store the new one right away.
  • If a refresh token is used a second time, Krunker treats it as stolen: the whole chain of refresh tokens from that sign-in is revoked, as are all of the player's access tokens for your app. The player has to sign in again.
  • So never refresh the same player's tokens concurrently. Refresh in one place, for example a minute before expires_in runs out.
  • The refreshed token keeps the scopes of the old one that the player still grants.
  • Refreshing fails with invalid_grant once the player has disconnected your app or is banned.

A session of krapio is bound to one access token and does not refresh by itself: refresh where you store the tokens, then make a new krunker.app(tokens.access_token).

Revoking

POST https://gapi.svc.krunker.io/oauth/revoke
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ...

token=krt_9mWv...

krunker.oauth.revoke(token)

  • Answers 200 with an empty body for any token, valid or not, as long as your client authentication is right (RFC 7009).
  • Revoking a refresh token revokes its whole chain. Access tokens already issued keep working until they expire, so revoke the current access token too when a user logs out of your app.
  • Revoking an access token ends only that token.
  • Revoking doesn't disconnect your app for the player; only the player can do that, in Krunker. A later sign-in with the same scopes is one click for them.

Token endpoint errors

The token and revoke endpoints use the standard OAuth error format: {"error": "...", "error_description": "..."}.

StatuserrorWhen
400invalid_grantThe code is unknown, expired, already used, from another client or redirect URI, or the code_verifier doesn't match. A refresh token that is unknown, expired, revoked or reused. The player disconnected the app or is banned
400unsupported_grant_typegrant_type isn't authorization_code or refresh_token
401invalid_clientUnknown client id, wrong secret, a secret sent by a public client, or a suspended app
429More than 600 requests per minute for your client id
500server_errorOur side failed; try again
503temporarily_unavailableRevoke only; try again

observed: a request without client authentication is checked for that first, whatever the grant type: 401 {"error": "invalid_client", "error_description": "client authentication failed"} with WWW-Authenticate: Basic realm="krunker" and Cache-Control: no-store. The reply carries X-RateLimit-Limit: 600, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window ends).

In krapio these are the usual errors (KrunkerBadRequestError, KrunkerUnauthorizedError, KrunkerRateLimitError, ...), and err.code is the error of the body, e.g. invalid_grant.


Scopes

Scopes are space-separated in the authorize request. profile is always included. A write scope includes its read scope: a token with trades:write can call the trades:read endpoints, and so on.

ScopeAllowsWrite
profileThe player's subject id, name, level, clan tag and premium/verified flags (/me). Always granted
stats:readLifetime stats, ranked profile per region and season, challenge progress
notifications:readKrunker Mail and system notices
inventory:readItems (instances, stacks, wear, paint, locks) and currency balances
inventory:write:skinsQuick-sell, paint, style and lock items (apps can never unlock)yes
inventory:write:currencySend KR to another playeryes
inventory:writeBoth inventory write scopesyes
trades:readOpen and completed trades, trade count
trades:writeCreate, accept, cancel and decline tradesyes, level 10
market:readThe player's own listings and market history
market:writeList, unlist and buy on the marketyes, level 10
friends:readFollowing and followers, with online status
friends:writeFollow and unfollow playersyes
dms:readDirect message conversations and messages
dms:writeSend DMs to the player's friends, shown as "via" your appyes
clan:readThe player's clan, its members and (for officers) join applications
maps:readThe player's published maps and their stats
events:subscribeReceive webhooks about the playerserver only
  • Every scope except profile needs approval from the Krunker team for your app.
  • Write scopes are for confidential clients only, need a privacy policy URL on the app, are shown to the player with a warning, and need a fresh 2FA code at consent. trades:write and market:write also need the player to be level 10, the same as in game.
  • events:subscribe is for confidential clients only, but it isn't a write scope: no warning and no 2FA code.
  • A public client that needs to act can use per-action approval instead of a write scope.

krapio exports the list as APP_SCOPES and the type AppScope.


Subjects

Players are never identified by their Krunker player id. Your app sees every player (the signed-in one and anyone else) as a subject id:

0f29b001-eb77-4d21-885f-c121a6511df4
  • It looks like a UUID, but treat it as an opaque string.
  • It is per app: the same player has a different subject in every app, so apps can't join their data on it.
  • It is stable: it stays the same when the player renames, disconnects or reconnects. Use it as the key for your users, not the name.
  • Endpoints that take a player (to, :sub) take a subject id. A subject from another app, or a made-up one, is 404 not_found.
  • To find a player by name, use GET /app/v1/players/by-name/:name.
  • Other players appear as { "sub": "...", "name": "..." }. Names are public and can change.

Item instance ids, trade ids and listing ids are global ids, the same everywhere in Krunker.


Conventions

  • Base URL: https://gapi.svc.krunker.io/app/v1. Every request sends Authorization: Bearer kat_.... Write requests send JSON bodies with Content-Type: application/json.
  • Success: { "data": ... }. Lists also carry "next_cursor" when there is another page.
  • Paging: pass next_cursor back as ?cursor= to get the next page. Cursors are opaque; don't build or parse them. ?limit= defaults to 50 and is capped at 100 (DMs: default 20, cap 50); 0 or a negative value is 400. A page can hold fewer items than the limit, so keep going while next_cursor is present.
  • Errors: { "error": { "code": "...", "message": "..." } }. Branch on code; message is human-readable and can change. See Errors.
  • Players appear as { "sub": "...", "name": "..." }. See Subjects.
  • Times are RFC 3339 UTC strings; durations are milliseconds (*_ms).
  • Ids are named after what they identify and are the same in reads, writes and webhooks: skin_index (catalog item), instance_id (one owned copy), listing_id, trade_id, notification_id, map_id, clan_id, currency_id, message_id.
  • Item names, images and rarities aren't in app responses. Look them up by skin_index in the public catalog, GET https://gapi.svc.krunker.io/data/skins (Skins of the game API, krunker.game.game.skins()).
  • Scopes: each request runs with the token's scopes that the player still grants. A missing scope is 403 insufficient_scope, with WWW-Authenticate: Bearer error="insufficient_scope", scope="...".

In krapio a single object comes back unwrapped (await me.stats.get() is the data), a list comes back as the page it is, { data, next_cursor? }, so the cursor is not lost:

const me = krunker.app(accessToken);
let cursor: string | undefined;
do {
    const page = await me.inventory.items({ cursor, limit: 100 });
    for (const item of page.data) console.log(item.skin_index, item.count);
    cursor = page.next_cursor;
} while (cursor);

limit is checked before the request (1 to 100, 1 to 50 for DMs). An error is the usual KrunkerHttpError subclass, with the body's code as err.code.

Rate limits

LimitValue
Per app600 requests per minute
Per app and player, reads120 requests per minute
Per app and player, writes20 requests per minute
Send KRAlso 5 per minute per app and player
DMsAlso 10 per minute and 200 per day per app and player
Approval requests20 per 10 minutes per app and player

Over a limit you get 429 rate_limited with Retry-After (seconds). The game's own limits and cooldowns apply on top: for example, the market allows one action at a time per player, and a trade can only be accepted a few seconds after it was created.

In krapio every krunker.app(accessToken) session tracks its own windows, since most of these are counted per player: a 429 for one player throws KrunkerRateLimitError and refuses that session's next calls locally until Retry-After has passed, without holding back the sessions of other players.


The Player

Scope profile, which every token has.

Me

krunker.app(accessToken).player.me()

The signed-in player. This is also the discovery document's userinfo_endpoint.

clan is omitted when the player has no clan. scopes lists the scopes this token can use right now. It sits next to data, so krapio returns the whole body here: const { data: player, scopes } = await me.player.me().

observed: without a token the reply is 401 {"error": {"code": "invalid_token", "message": "missing or malformed access token"}}, with a made-up one the message is invalid or expired access token. Both carry WWW-Authenticate: Bearer error="invalid_token" and no rate limit headers.

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/players/by-name/:name, and `data` of GET /app/v1/me
data.substringthe player's subject id in this app, the key to store users under
data.namestring
data.levelnumber
data.clanstringthe clan tag, absent without a clan
data.premiumboolean
data.verifiedboolean
scopes"profile" | "stats:read" | "notifications:read" | "inventory:read" | "inventory:write:skins" | "inventory:write:currency" | "inventory:write" | "trades:read" | "trades:write" | "market:read" | "market:write" | "friends:read" | "friends:write" | "dms:read" | "dms:write" | "clan:read" | "maps:read" | "events:subscribe"[]what this token can use right now

Look up a player by name

krunker.app(accessToken).player.byName(name)

Returns the same fields as /me (without scopes) for any player, so you can get their subject id. Banned and hidden accounts are 404 not_found.

Parameters:

NameTypeLocationRequiredDescription
namestringpathyes

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/players/by-name/:name, and `data` of GET /app/v1/me
data.substringthe player's subject id in this app, the key to store users under
data.namestring
data.levelnumber
data.clanstringthe clan tag, absent without a clan
data.premiumboolean
data.verifiedboolean

The item object

Used by the inventory, trades and market listings (AppItem in krapio).

{
  "instance_id": 200107647,
  "skin_index": 7584,
  "count": 1,
  "stackable": false,
  "locked": true,
  "wear": 0.62,
  "wear_tier": "Wrecked",
  "serial": 42,
  "paint": "#dc3c3c",
  "style": 3,
  "nametag": "my AWP",
  "pattern_seed": 693909,
  "kounter": { "kills": 1285 }
}
  • instance_id is the copy's global id. Stackable items have no instance_id; they are counted with count and addressed by skin_index.
  • locked (inventory only): the player locked this copy or stack in game. Apps can't use locked items.
  • The other fields appear only when the copy has them: wear (0 is best), wear_tier (Flawless, Tested, Trashed or Wrecked), serial (mint number), paint (hex colour) or paint_shader (paint shader id), style, nametag, pattern_seed (0 to 999999) and kounter (kill-counter values by stat: kills, hskills, aikills, headshots, hits, shots, jumps).

Stats

Scope stats:read.

Lifetime Stats

krunker.app(accessToken).stats.get()

Lifetime stats. KR and other currency fields aren't included.

accuracy is a percentage (hits / shots). classes lists every class in game order.

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/stats, lifetime stats without KR or any other currency
data.levelnumber
data.scorenumber
data.killsnumber
data.deathsnumber
data.kdrnumber
data.winsnumber
data.lossesnumber
data.gamesnumber
data.time_played_msnumber
data.accuracynumberhits / shots as a percentage
data.combatobject
data.combat.assistsnumber
data.combat.headshotsnumber
data.combat.legshotsnumber
data.combat.wallbangsnumber
data.combat.melee_killsnumber
data.combat.fist_killsnumber
data.combat.thrown_killsnumber
data.combat.shotsnumber
data.combat.hitsnumber
data.combat.nukesnumber
data.combat.airdropsnumber
data.combat.airdrops_stolennumber
data.combat.slimersnumber
data.combat.juggernautsnumber
data.combat.juggernauts_killednumber
data.combat.war_machinesnumber
data.combat.crouchesnumber
data.combat.spraysnumber
data.classesobject[]every class in game order
data.classes[].class_idnumber
data.classes[].namestring
data.classes[].scorenumber
data.classes[].levelnumber
data.raidsobject[]
data.raids[].map_idnumber
data.raids[].completionsnumber
data.raids[].attemptsnumber
data.raids[].best_time_msnumber
data.raids[].ai_killsnumber
data.raids[].boss_killsnumber
data.raids[].deathsnumber

Ranked Stats

krunker.app(accessToken).stats.ranked(season)

Ranked profile per region. season defaults to the current season and must be between 1 and current_season.

  • During placement (the first 6 matches) rank is "Unranked", mmr is null and placement_matches_remaining counts down.
  • peak_mmr is present once the season tracks it. regions is empty when the player hasn't played that season.

Parameters:

NameTypeLocationRequiredDescription
seasonintegerqueryno

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/stats/ranked
data.seasonnumber
data.current_seasonnumber
data.season_ends_atstring
data.regionsobject[]empty when the player hasn't played that season
data.regions[].regionnumber
data.regions[].region_namestring
data.regions[].rankstring"Unranked" during the 6 placement matches
data.regions[].mmrnumber or nullnull during placement
data.regions[].peak_mmrnumberpresent once the season tracks it
data.regions[].placement_matches_remainingnumber
data.regions[].matchesnumber
data.regions[].winsnumber
data.regions[].lossesnumber
data.regions[].killsnumber
data.regions[].deathsnumber
data.regions[].assistsnumber
data.regions[].scorenumber
data.regions[].damage_donenumber
data.regions[].time_played_msnumber
data.regions[].best_kills_in_matchnumber
data.regions[].best_damage_in_matchnumber

Challenges

krunker.app(accessToken).stats.challenges({ type, status, cursor, limit })

Active challenges with the player's progress. Paged.

QueryDescription
typemap, weapon, nightmare, ranked, daily, weekly or event
statusall (default), completed or in_progress
cursor, limitPaging

requirement and rewards are the game's own challenge definition, passed through as they are. ends_at is absent for challenges without an end date.

Parameters:

NameTypeLocationRequiredDescription
type"map" | "weapon" | "nightmare" | "ranked" | "daily" | "weekly" | "event"queryno
status"all" | "completed" | "in_progress"querynoall when omitted
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].challenge_idnumber
data[].namestring
data[].type"map" | "weapon" | "nightmare" | "ranked" | "daily" | "weekly" | "event"the `type` filter of GET /app/v1/stats/challenges
data[].iconnumber
data[].requirementobjectthe game's own challenge definition, passed through
data[].targetnumber
data[].progressnumber
data[].completedboolean
data[].rewardsobjectthe game's own reward definition, passed through
data[].ends_atstringabsent for a challenge without an end date
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Inventory

Scope inventory:read.

Items

krunker.app(accessToken).inventory.items({ cursor, limit })

The player's items, the same set the in-game inventory shows (paged). Copies listed on the market are left out, and stack counts exclude listed units.

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].instance_idnumberthe copy's global id; a stackable item has none and is addressed by `skin_index` and `count`
data[].skin_indexnumberthe catalog item
data[].countnumber
data[].stackableboolean
data[].lockedbooleaninventory only: the player locked this copy or stack in game, apps can't use it
data[].wearnumber0 is best
data[].wear_tier"Flawless" | "Tested" | "Trashed" | "Wrecked"how worn a copy is, from `wear`
data[].serialnumberthe mint number
data[].paintstringhex colour
data[].paint_shadernumberthe paint shader id, instead of `paint`
data[].stylenumber
data[].nametagstring
data[].pattern_seednumber0 to 999999
data[].kounterobjectthe kill counter of a copy, by stat
data[].kounter.killsnumber
data[].kounter.hskillsnumber
data[].kounter.aikillsnumber
data[].kounter.headshotsnumber
data[].kounter.hitsnumber
data[].kounter.shotsnumber
data[].kounter.jumpsnumber
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Currencies

krunker.app(accessToken).inventory.currencies()

Balances. KR and Junk are always present; other currencies only when the player holds some.

Response Fields:

FieldTypeDescription
dataobject[]
data[].currency_idnumber
data[].namestring
data[].symbolstring
data[].amountnumber

Trades

Scope trades:read. Creating, accepting and cancelling are writes and are not in krapio.

List Trades

krunker.app(accessToken).trades.list({ status, cursor, limit })

status is open (default) or completed. Open trades include both directions; completed trades are newest first.

  • role is sender when the player created the trade and recipient when it was sent to them.
  • offered is what the sender gives; requested is what the sender asks for.
  • partner is null if that account no longer exists.

Parameters:

NameTypeLocationRequiredDescription
status"completed" | "open"querynoopen when omitted
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].trade_idnumber
data[].status"open" | "completed"
data[].role"sender" | "recipient"sender when the player created the trade, recipient when it was sent to them
data[].partnerobject or nullnull when that account no longer exists
data[].partner.substring
data[].partner.namestring
data[].offeredobjectone side of a trade
data[].offered.itemsobject[]
data[].offered.currenciesobject[]
data[].requestedobjectone side of a trade
data[].requested.itemsobject[]
data[].requested.currenciesobject[]
data[].messagestring
data[].created_atstring
data[].completed_atstring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Trade Count

krunker.app(accessToken).trades.count()

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/trades/count
data.opennumber
data.completednumber

Market

Scope market:read. Only the player's own market data. Public market data (listings, prices) is on the public market endpoints of the game API and needs no scope.

Listings

krunker.app(accessToken).market.listings()

All of the player's active listings. Not paged: the game caps active listings.

Response Fields:

FieldTypeDescription
dataobject[]
data[].listing_idnumber
data[].pricenumberKR
data[].itemobjectone copy or one stack, as the inventory, trades and listings show it; names, images and rarities are in /data/skins by `skin_index`
data[].item.instance_idnumberthe copy's global id; a stackable item has none and is addressed by `skin_index` and `count`
data[].item.skin_indexnumberthe catalog item
data[].item.countnumber
data[].item.stackableboolean
data[].item.lockedbooleaninventory only: the player locked this copy or stack in game, apps can't use it
data[].item.wearnumber0 is best
data[].item.wear_tier"Flawless" | "Tested" | "Trashed" | "Wrecked"how worn a copy is, from `wear`
data[].item.serialnumberthe mint number
data[].item.paintstringhex colour
data[].item.paint_shadernumberthe paint shader id, instead of `paint`
data[].item.stylenumber
data[].item.nametagstring
data[].item.pattern_seednumber0 to 999999
data[].item.kounterobjectthe kill counter of a copy, by stat
data[].listed_atstring

History

krunker.app(accessToken).market.history({ cursor, limit })

Completed sales and purchases plus cancelled listings, newest first (paged). Quick-sells aren't included.

side is sold or bought; status is completed or cancelled. A cancelled listing has no counterparty.

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].listing_idnumber
data[].side"sold" | "bought"
data[].status"completed" | "cancelled"
data[].skin_indexnumber
data[].pricenumberKR
data[].counterpartyobjectanother player as an app sees them: the subject id is per app and stable, the name is public and can change
data[].counterparty.substring
data[].counterparty.namestring
data[].atstring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Friends

Scope friends:read.

Following and Followers

krunker.app(accessToken).friends.following({ cursor, limit }), .friends.followers({ cursor, limit })

Newest first (paged). Banned and hidden accounts are left out.

online is omitted when presence is temporarily unavailable; treat a missing value as unknown, not offline.

GET /app/v1/friends/following

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].sincestring
data[].onlinebooleanabsent while presence is unavailable: unknown, not offline
data[].substring
data[].namestring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

GET /app/v1/friends/followers

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].sincestring
data[].onlinebooleanabsent while presence is unavailable: unknown, not offline
data[].substring
data[].namestring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Maps

Scope maps:read.

Published Maps

krunker.app(accessToken).maps.list({ cursor, limit })

The player's published maps, newest first (paged). Map KR balances aren't included.

description is omitted when empty. playtime_ms is the total time players have spent in the map.

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].map_idnumber
data[].namestring
data[].descriptionstringabsent when empty
data[].votesnumber
data[].playsnumber
data[].playtime_msnumberthe total time players have spent in the map
data[].featuredboolean
data[].verifiedboolean
data[].restrictedboolean
data[].categorynumber
data[].updatesnumber
data[].created_atstring
data[].updated_atstring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Clan

Scope clan:read.

Get Clan

krunker.app(accessToken).clan.get()

  • When the player has no clan: { "data": { "clan": null } }.
  • role is owner, commander, captain, soldier or recruit.
  • is_officer means the player can see join applications (the owner or a captain, as in game). The clan's KR bank isn't included.

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/clan; only `clan: null` when the player has no clan
data.clanobject or null
data.clan.clan_idnumber
data.clan.namestring
data.clan.scorenumber
data.clan.ranknumber
data.clan.logonumber
data.clan.banner_colorstring
data.clan.member_countnumber
data.role"owner" | "commander" | "captain" | "soldier" | "recruit"a member's role, highest first
data.is_officerbooleanthe player can see join applications (the owner or a captain)

Clan Members

krunker.app(accessToken).clan.members({ cursor, limit })

Paged. 404 not_found when the player has no clan.

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].role"owner" | "commander" | "captain" | "soldier" | "recruit"a member's role, highest first
data[].scorenumber
data[].substring
data[].namestring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Clan Applications

krunker.app(accessToken).clan.applications({ cursor, limit })

Pending join requests, oldest first (paged). Officers only: 403 not_clan_officer otherwise, 404 not_found without a clan.

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].substring
data[].namestring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Notifications

Scope notifications:read.

List Notifications

krunker.app(accessToken).notifications.list({ unread, cursor, limit })

The player's Krunker Mail, newest first (paged). Reading through the API never marks mail as read. ?unread=true returns unread mail only.

  • category matches the in-game mail tabs: followers, clan, hub or inbox.
  • from.system is true for mail from Krunker, which has no sub. A sender whose account no longer exists is { "name": "Unknown", "system": false }.
  • link is the game's own reference for the mail (often a player or clan name).

Parameters:

NameTypeLocationRequiredDescription
unread"true"querynoonly unread mail
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].notification_idnumber
data[].category"followers" | "clan" | "hub" | "inbox"the in-game mail tab
data[].subjectstring
data[].textstring
data[].linkstringthe game's own reference for the mail, often a player or clan name
data[].fromobjectwho a mail is from; Krunker itself has no `sub`, a deleted account is `{name: "Unknown", system: false}`
data[].from.substring
data[].from.namestring
data[].from.systemboolean
data[].readboolean
data[].sent_atstring
data[].read_atstring
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Unread Count

krunker.app(accessToken).notifications.count()

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/notifications/count
data.unreadnumber

Direct Messages

Scopes: dms:read to read conversations and messages, dms:write to send as the player (it includes dms:read). Krunker keeps DMs for 30 days. Messages sent through any app carry via (the app's name), and the game shows them to both players as "via <app>".

Conversations

krunker.app(accessToken).dms.conversations({ cursor, limit })

The player's conversations, newest first. limit is 1 to 50 (default 20; higher values are lowered to 50, krapio refuses them before the request), cursor is the previous page's next_cursor. unread counts messages from the peer the player hasn't read in game. Reading through the API never marks anything read.

Parameters:

NameTypeLocationRequiredDescription
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
dataobject[]
data[].peerobjectanother player as an app sees them: the subject id is per app and stable, the name is public and can change
data[].peer.substring
data[].peer.namestring
data[].unreadnumbermessages from the peer the player hasn't read in game
data[].last_messageobjectone direct message
data[].last_message.message_idnumber
data[].last_message.from_meboolean
data[].last_message.textstring
data[].last_message.sent_atstring
data[].last_message.readbooleanwhether the recipient has read it
data[].last_message.viastringthe name of the app it was sent through
next_cursorstringopaque, pass it back as `cursor`; absent on the last page

Messages

krunker.app(accessToken).dms.messages(sub, { cursor, limit })

Messages with one player, newest first; cursor pages to older messages. read says whether the recipient has read the message. Note that peer is next to data, so krapio returns the whole body here.

Parameters:

NameTypeLocationRequiredDescription
substringpathyes
cursorstringquerynothe `next_cursor` of the previous page
limitintegerqueryno1 to 100, 50 when omitted (dms: 1 to 50, 20 when omitted)

Response Fields:

FieldTypeDescription
peerobjectanother player as an app sees them: the subject id is per app and stable, the name is public and can change
peer.substring
peer.namestring
dataobject[]
data[].message_idnumber
data[].from_meboolean
data[].textstring
data[].sent_atstring
data[].readbooleanwhether the recipient has read it
data[].viastringthe name of the app it was sent through
next_cursorstringopaque, absent on the last page

Sending a Message

Scope dms:write, a write, not in krapio. POST /app/v1/dms/:sub with the body { "text": "..." }; send X-Idempotency-Key as with other writes.

The rules of the game apply: the recipient must be a friend (mutual follow, or a conversation in the last 30 days), the text is 1 to 512 bytes of UTF-8 (trimmed), and the player's own send rate (5 messages per 15 seconds, shared with the game) applies. Each app can also send at most 10 messages per minute and 200 per day per player.

{ "data": { "message_id": 181, "from_me": true, "text": "gg", "sent_at": "2026-11-06T22:40:02.469Z", "read": false, "via": "My Tracker" } }

The message is delivered live to the recipient and to the player's open game clients, labelled "via <app>".

StatuscodeWhen
400invalid_requestBad limit or cursor, body not JSON, empty or invalid text
400text_too_longText over 512 bytes
403not_friendsThe recipient isn't a friend of the player
404not_found:sub isn't a player known to your app, or is the player themself
429rate_limitedThe player is sending too fast (Retry-After: 15), or a general limit
429dm_limit_reachedYour app's per-player DM limit; Retry-After says when the next send fits
503temporarily_unavailableMessaging is down; try again later

Acting for the player

None of this is in krapio. The library sends no write on any tier; the endpoints are documented so the whole API is in one place, and the body and reply types are exported (AppListBody, AppListResult, AppCreateTradeBody, ...). Every path below is under /app/v1.

Write endpoints run the same rules as the game: level gates, fees, cooldowns, bans, locks, and market and trade limits. Every call is recorded in the player's app activity.

ScopeEndpoints
market:writeList, bulk list, unlist, buy, buy several
trades:writeCreate, accept, cancel or decline, decline all
inventory:write:skinsQuick-sell, bulk quick-sell, paint, style, lock
inventory:write:currencySend KR
friends:writeFollow, unfollow
dms:writeSend a DM (see Sending a Message)
  • Balances: responses that change the player's money include kr (KR after the call) and, for quick-sells, junk.
  • Players in inputs (to, :sub) are subject ids.
  • Items: a single copy is addressed by instance_id (and its skin_index), a stack by skin_index and count, exactly as GET /app/v1/inventory/items shows them.

Locked items

Players lock items in game to keep them safe. Apps can never use a locked item: listing, quick-selling, painting (including with a locked paint), styling and trading it are refused with 422 item_locked. When you name an item without an instance_id, the call is refused if any copy of it is locked, so pass instance_id to use an unlocked copy. Apps can lock items but never unlock them.

Idempotency

Send X-Idempotency-Key: <uuid> on every write (up to 255 characters).

  • A retry with the same key (same method and path, same app and player) within 24 hours returns the stored response instead of running again, with the header Idempotent-Replayed: true.
  • While the first request is still running, a retry gets 409 idempotency_in_progress.
  • 429 and 5xx responses aren't stored, so you can retry them with the same key. A 500 server_error is safe to retry with the same key.
  • Use a new key for every new action.
  • The key doesn't apply to approval requests (Krunker-Approval: request): each one creates a new action.

Market (market:write)

The player needs level 10 (market_level_too_low). Listing charges the game's listing fee (currently 10% of the price), which isn't refunded on unlist.

RequestBodyReply data
POST /market/listings{skin_index, instance_id?, price}{listing_id, skin_index, instance_id?, price, kr}
POST /market/listings/bulk{items: {skin_index, instance_id?, price, count?}[]}{listed, kr, results: {skin_index, instance_id?, listed, listing_ids}[]}
DELETE /market/listings/:listing_idnone{listing_id, unlisted: true}
POST /market/purchase{listing_id, max_price}{listing_id, skin_index, instance_id?, price, kr}
POST /market/buy-multiple{skin_index, count, max_total}{skin_index, bought, spent, kr, instance_ids}

List an item. For a non-stackable item instance_id is optional (an unlisted copy is picked); pass it when the player has several copies. For a stackable item send only skin_index and price; one unit is listed, and the reply has no instance_id.

{ "skin_index": 7820, "instance_id": 200000470, "price": 500 }
{ "data": { "listing_id": 30002326, "skin_index": 7820, "instance_id": 200000470, "price": 500, "kr": 525359 } }

List several items. Up to 100 units per call. count (default 1) lists that many units of a stackable item. Entries are independent: one failing doesn't undo the others, but account-wide refusals (listing cap, KR for the fee, level) stop the run. A locked item in any entry refuses the whole call. An entry that failed has "listed": 0 plus error and code (for example market_price_too_low).

{
  "items": [
    { "skin_index": 7820, "instance_id": 200000470, "price": 500 },
    { "skin_index": 7777, "price": 300, "count": 2 }
  ]
}
{
  "data": {
    "listed": 3,
    "kr": 525655,
    "results": [
      { "skin_index": 7820, "instance_id": 200000470, "listed": 1, "listing_ids": [30002333] },
      { "skin_index": 7777, "listed": 2, "listing_ids": [30002331, 30002332] }
    ]
  }
}

Unlist. 404 not_found if the listing isn't the player's or was already taken down; 422 market_listing_gone if it already sold.

{ "data": { "listing_id": 30002326, "unlisted": true } }

Buy a listing. max_price is required: the price you showed the player. If the listing now costs more, the call fails with market_price_changed. A listing that sold or doesn't exist is 422 market_listing_gone. instance_id, the copy received, is omitted for stackable items.

{ "listing_id": 24971780, "max_price": 41 }
{ "data": { "listing_id": 24971780, "skin_index": 7820, "instance_id": 200107967, "price": 41, "kr": 525709 } }

Buy several of one item. Buys the cheapest count listings of an item (1 to 1000) in one transaction, all or nothing. max_total is the total you showed the player; if the cheapest listings now cost more, nothing is bought (market_price_changed). instance_ids lists the copies received for non-stackable items.

{ "skin_index": 2583, "count": 2, "max_total": 300 }
{ "data": { "skin_index": 2583, "bought": 2, "spent": 300, "kr": 525409, "instance_ids": [] } }

Trades (trades:write)

Both players need level 10 (trade_level_too_low). The game's item caps (5 per side, 20 for premium) and trade fee apply; the fee is charged to the player who creates the trade and is waived for premium players.

RequestBodyReply data
POST /trades{to, give: {skin_index, instance_ids? | count?}[], receive: [...], message?}{trade_id, to: {sub, name}, kr}
POST /trades/:trade_id/acceptnone{trade_id, accepted: true, kr}
POST /trades/:trade_id/cancelnone{trade_id, cancelled: true}
POST /trades/decline-allnone{declined: true}

Create a trade. give is what the player offers and receive what they ask for. For a non-stackable item pin copies with instance_ids, or give a count and the game picks the copies; for a stackable item give a count. message is up to 500 bytes.

{
  "to": "21054d5f-757e-4583-a5ef-b60ad7e3899f",
  "give": [{ "skin_index": 7822, "instance_ids": [200000484] }],
  "receive": [{ "skin_index": 7776, "count": 2 }],
  "message": "gg"
}
{ "data": { "trade_id": 8880926, "to": { "sub": "21054d5f-757e-4583-a5ef-b60ad7e3899f", "name": "GamerRenamed" }, "kr": 525357 } }

Accept takes a trade offered to the player.

{ "data": { "trade_id": 8880927, "accepted": true, "kr": 525357 } }

Cancel cancels the player's own offer or declines one made to them.

{ "data": { "trade_id": 8880926, "cancelled": true } }

Decline all declines every incoming trade.

{ "data": { "declined": true } }

Items (inventory:write:skins)

RequestBodyReply data
POST /inventory/quick-sell{skin_index, instance_id?, action, amount?}{skin_index, remaining, kr, junk}
POST /inventory/quick-sell/bulk{action, items: {instance_id, skin_index}[]}{sold: number[], skipped: {instance_id, reason}[], kr, junk}
POST /inventory/items/:instance_id/paint{skin_index, paint_skin_index}{instance_id, paint | paint_shader, paint_remaining}
POST /inventory/items/:instance_id/style{skin_index, style}{instance_id, style}
POST /inventory/locks{instance_id} or {skin_index}{skin_index, instance_id?, locked: true}

Quick-sell sells an item back to Krunker. The player needs level 10.

{ "skin_index": 7820, "instance_id": 200000481, "action": "kr", "amount": "one" }
{ "data": { "skin_index": 7820, "remaining": 21, "kr": 525369, "junk": 1189.94 } }
  • action: "kr" or "junk" (the item must have a value in that currency), or "destroy" (only for items with no value).
  • amount: "one" (default), "all_but_one" or "all".
  • instance_id: the copy to sell, for "one" on a non-stackable item. For stackable items send only skin_index (an instance_id is 400 invalid_request).
  • remaining is how many copies the player still has.

Quick-sell many copies takes up to 250 non-stackable copies in one transaction. The reason of a skipped copy is not_owned, no_value or unavailable (listed or stackable).

{ "action": "kr", "items": [{ "instance_id": 200000487, "skin_index": 7821 }] }
{ "data": { "sold": [200000487], "skipped": [{ "instance_id": 999, "reason": "not_owned" }], "kr": 525379, "junk": 1189.94 } }

Paint uses one paint from the player's inventory. Shader paints return paint_shader (a number) instead of paint.

{ "skin_index": 7793, "paint_skin_index": 7776 }
{ "data": { "instance_id": 200000343, "paint": "#dc3c3c", "paint_remaining": 43 } }

Pick a style.

{ "skin_index": 7794, "style": 1 }
{ "data": { "instance_id": 200000344, "style": 1 } }

Lock takes { "instance_id": 200000345 } for a copy, or { "skin_index": 7779 } for a stackable item (locks the whole stack). An item listed on the market can't be locked (item_listed).

{ "data": { "skin_index": 7793, "instance_id": 200000345, "locked": true } }

Send KR (inventory:write:currency)

POST /inventory/gift

{ "to": "21054d5f-757e-4583-a5ef-b60ad7e3899f", "amount": 10, "message": "for the trade" }

The minimum is 10 KR, and the sender also pays the game's 10% fee. message is up to 300 characters and goes into the recipient's Krunker Mail.

{ "data": { "to": { "sub": "21054d5f-757e-4583-a5ef-b60ad7e3899f", "name": "GamerRenamed" }, "amount": 10, "kr": 525368 } }

Follow (friends:write)

PUT /friends/following/:sub follows a player; DELETE /friends/following/:sub unfollows.

{ "data": { "sub": "21054d5f-757e-4583-a5ef-b60ad7e3899f", "name": "GamerRenamed", "following": true } }

Per-action approval

Instead of holding a write scope, an app can ask the player to approve one write at a time. This is how public clients (read scopes only) can act, and an option for confidential apps that only act now and then. Your app still needs the Krunker team's approval for the endpoint's scope; the player's grant doesn't need to include it.

Requesting an approval is a write, so krapio does not send it. It does read the outcome (Action Status) and the redirect back (parseCallback).

Supported endpoints:

  • POST /market/listings, DELETE /market/listings/:listing_id, POST /market/purchase
  • POST /trades, POST /trades/:trade_id/accept, POST /trades/:trade_id/cancel
  • POST /inventory/gift
  • PUT /friends/following/:sub, DELETE /friends/following/:sub

Every other write endpoint (bulk endpoints, quick-sell, paint, style, locks, decline all, DMs) answers 400 approval_unavailable to the approval header.

1. Request the action

Call the endpoint exactly as usual, with these headers added:

HeaderRequiredDescription
Krunker-Approvalyesrequest
Krunker-Approval-RedirectnoOne of your registered redirect URIs (exact match), where the player comes back afterwards
Krunker-Approval-Statewith a redirectYour random value (1 to 500 characters), returned unchanged

Krunker runs some checks right away (for example that the item exists and isn't locked, that the listing exists and is within max_price, that the player is part of the trade, that the recipient exists and isn't the player) and answers 202 Accepted, with Location set to approve_url (AppActionRequest in krapio):

{
  "data": {
    "action_id": "act_6Hc2...",
    "status": "pending",
    "approve_url": "https://krunker.io/oauth/authorize?action=act_6Hc2...",
    "expires_at": "2026-11-07T00:01:01Z"
  }
}

The full game rules (level, balance, ownership, ...) run when the player approves.

2. Send the player to approve_url

Krunker shows exactly that action in plain words ("Unfollow GamerRenamed", "List AK Ruby for 1,200 KR", ...) and asks for the player's 2FA code. Only the player the token belongs to can approve it; signed in as someone else, they are told it's for another account. It expires after 10 minutes, runs at most once, and is refused if the player has disconnected your app.

3. The player comes back

On approval, Krunker runs the request once, as the player, through the same endpoint. With a redirect, the player then returns to:

https://example.com/callback?action_id=act_6Hc2...&state=...&status=approved

status is approved, denied or failed. Check state, and treat status as a hint only. parseCallback(url, expectedState) returns this as { kind: "action", actionId, status }.

Action Status

krunker.app(accessToken).actions.get(actionId)

The outcome of an action, with any valid token of the same player and app.

statusMeaning
pendingWaiting for the player
approvedIt ran and succeeded; result is the body the direct call would have returned
failedIt ran and the endpoint refused it; result holds the normal error body and result_status its HTTP status
deniedThe player declined
expiredNobody approved it within 10 minutes

Actions are kept for 24 hours after they are created or decided. result_status and result are absent until the action has run.

Errors specific to approval requests:

StatuscodeWhen
400approval_unavailableThe endpoint doesn't support approval
400invalid_redirect_uriKrunker-Approval-Redirect isn't one of your redirect URIs
400invalid_requestKrunker-Approval isn't request, or the state is missing or too long
403insufficient_scopeYour app isn't approved for the endpoint's scope
413invalid_requestThe body is over 16 KB
429rate_limitedMore than 20 approval requests in 10 minutes for this player (Retry-After: 600)

Parameters:

NameTypeLocationRequiredDescription
action_idstringpathyes

Response Fields:

FieldTypeDescription
dataobjectGET /app/v1/actions/:action_id, kept for 24 hours
data.action_idstring
data.typestringe.g. `follow.remove`
data.status"pending" | "approved" | "failed" | "denied" | "expired"where a per-action approval stands
data.summaryobjectwhat the player was shown
data.created_atstring
data.expires_atstring
data.decided_atstring
data.result_statusnumberthe http status of the call, once the action has run
data.resultunknownthe body the direct call would have returned (approved) or its error body (failed)

Webhooks

An app with events:subscribe can get a signed HTTP POST when something happens to a player who authorised it. Each event is about one player your app acts for. Players only ever appear as your app's subject ids, plus the public name of other players. Events are signals: they carry ids, not content; fetch the details with the read endpoints.

These are not the webhooks of the developer API: those belong to a developer key and carry public events (map.featured), these belong to an app and carry a player's events. The headers and the signature are the same, so verifyWebhook checks both.

Setup

  1. Request events:subscribe for your app on its page; the Krunker team reviews it.
  2. Open Manage webhook on the app page and create the webhook: an https:// URL (public host, up to 500 characters) and the event types you want. The signing secret whsec_... is shown once.
  3. Click Verify. Krunker sends 10 webhook.verify POSTs in random order, some correctly signed and some not. Correctly signed ones must get a 2xx and the others a 401. The check stops at the first wrong answer, and nothing is delivered until it passes.
  4. Players authorise your app with events:subscribe and the read scope of each event type you want for them. Players can untick scopes, so you may get some types for some players only.

Each app has one webhook. You can turn it off and on, send a webhook.test event, rotate the secret and see the last 50 deliveries with Redeliver. Rotating the secret needs a new Verify; changing the URL starts a new check.

Event types

TypeWhenPlayer scope needed (besides events:subscribe)data
trade.receivedSomeone sent the player a trade offertrades:read or trades:writetrade_id, from
trade.completedA trade of the player went through (either side, or an in-game direct trade)trades:read or trades:writetrade_id, partner
market.soldOne of the player's listings soldmarket:read or market:writelisting_id, skin_index, price (KR), buyer
dm.receivedThe player received a DMdms:read or dms:writemessage_id, from
friend.followedSomeone followed the playerfriends:read or friends:writefollower
notification.receivedThe player got Krunker Mail or a system noticenotifications:readnotification_id, system, from (player mail only)
grant.revokedThe player disconnected your app, Krunker revoked it, or the account was deletednone (sent whenever the grant had events:subscribe)reason: player, staff or deleted

from, partner, buyer and follower are { "sub": "...", "name": "..." }. To get the details:

EventFetch withMatch on
trade.received, trade.completedGET /app/v1/trades (open or completed)trade_id
market.soldGET /app/v1/market/history (side sold)listing_id
dm.receivedGET /app/v1/dms/:sub with from.submessage_id
friend.followedGET /app/v1/friends/followersfollower.sub
notification.receivedGET /app/v1/notificationsnotification_id

After grant.revoked your tokens for that player stop working. The subject stays the same if the player connects your app again. With reason deleted, delete what you stored about that player.

Delivery

POST to your URL with Content-Type: application/json and User-Agent: Krunker-Webhooks/1.0:

{
  "id": 8,
  "type": "dm.received",
  "created_at": "2026-11-06T22:47:56Z",
  "sub": "b3c35209-38a9-44dc-8c2b-733e9ffcbba7",
  "data": {
    "from": { "sub": "72abe052-1ef8-40b6-b0c4-efc03519e69c", "name": "GamerRenamed" },
    "message_id": 182
  }
}
  • id is the event id, unique per event in your app. Retries and redeliveries repeat it, so use it to de-duplicate. sub is the player the event is about.
  • webhook.test has id 0, no sub and a data.message. It is sent once, without retries.
  • Headers: Krunker-Event-Id, Krunker-Event-Type, Krunker-Delivery-Id, Krunker-Delivery-Attempt and Krunker-Signature.
  • Answer with a 2xx within 10 seconds. Redirects aren't followed.
  • Order isn't guaranteed; use created_at and the ids.

Verifying signatures

Krunker-Signature: t=1762469276,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 is the hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret as the key. Compute it over the raw body bytes (before any JSON parsing), compare in constant time, reject old t values (for example older than 5 minutes), and answer 401 when it doesn't match.

In krapio that is verifyWebhook, and the parsed body is an AppWebhookEvent, a union that narrows on type:

import { verifyWebhook, WEBHOOK_HEADERS, type AppWebhookEvent } from "krapio";

const raw = await request.text();
if (!await verifyWebhook(raw, request.headers.get(WEBHOOK_HEADERS.signature), process.env.KRUNKER_WEBHOOK_SECRET!)){
    return new Response("bad signature", { status: 401 }); // the Verify check expects exactly this
}
const event = JSON.parse(raw) as AppWebhookEvent;
if (event.type === "market.sold") console.log(event.sub, event.data.listing_id, event.data.price);
return new Response(null, { status: 204 });

Retries and auto-disable

  • A delivery that doesn't get a 2xx is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h and 8 h: 10 attempts over about a day.
  • If deliveries keep failing for that long with no success, the webhook is turned off and you get a Krunker Mail. Fix the endpoint and turn it back on; it is verified again.
  • Before each attempt Krunker checks again that the player still grants the scopes and isn't banned; if not, the delivery is cancelled.
  • Events are kept 30 days. Events that happen while the webhook is off or not verified, or the app is suspended, aren't queued for it.

Errors

App API errors are { "error": { "code": "...", "message": "..." } }. The token and revoke endpoints use the OAuth format instead (see Token endpoint errors).

StatuscodeWhen
400invalid_requestA malformed body or parameter (limit, cursor, status, season, ...)
400approval_unavailablePer-action approval isn't supported on this endpoint
400invalid_redirect_uriAn approval redirect that isn't registered
400text_too_longA DM over 512 bytes
401invalid_tokenMissing, malformed, expired or revoked token; app suspended; player banned or disconnected the app
403insufficient_scopeThe token (or, for approvals, your app) lacks the endpoint's scope
403not_clan_officerClan applications for a player who isn't an officer
403not_friendsA DM to someone who isn't the player's friend
404not_foundUnknown subject, listing, trade, action or player; no clan
409busyThe player's account is busy with another action; retry after Retry-After (10 s)
409idempotency_in_progressA request with the same idempotency key is still running
413invalid_requestAn approval request body over 16 KB
422item_lockedThe request touches an item the player locked
422game codesA game rule refused it (below)
422rejectedAny other game refusal; read message
429rate_limitedOver a rate limit; see Retry-After
429dm_limit_reachedYour app's per-player DM limit
500server_errorOur side failed. Writes are safe to retry with the same idempotency key
503temporarily_unavailableA dependency is down; retry later

Game codes (status 422) you may see on writes:

AreaCodes
Items and KRitem_not_owned, item_listed, insufficient_funds, self_target
Marketmarket_disabled, market_maintenance, market_busy, market_rate_limited, market_level_too_low, market_invalid_account, market_insufficient_funds, market_item_not_found, market_item_not_owned, market_item_not_sellable, market_item_already_listed, market_item_already_sold, market_listing_gone, market_self_purchase, market_max_items, market_price_too_low, market_price_too_high, market_price_changed, market_not_enough_listings
Quick-sellmarket_quick_sell_not_sellable, market_quick_sell_no_value, market_quick_sell_invalid_action, market_quick_sell_invalid_amount, market_quick_sell_failed
Tradestrade_level_too_low, trade_player_not_found, trade_invalid_offer, trade_message_too_long, trade_max_items_exceeded, trade_item_not_owned, trade_item_not_tradable, trade_proc_error
Paint and styleitems_paint_not_owned, items_paint_invalid_type, items_paint_no_color, items_paint_def_missing, items_paint_insufficient, items_paint_target_invalid, items_style_target_invalid, items_style_invalid_index

New codes can be added; treat an unknown 422 code like rejected.

In krapio:

StatusErrorNotes
400KrunkerBadRequestError
401KrunkerUnauthorizedErrorthe token is dead: refresh, or sign the player in again
403KrunkerForbiddenErrorerr.code tells insufficient_scope from not_clan_officer
404KrunkerNotFoundError
429KrunkerRateLimitErrorretryAfter from Retry-After
5xxKrunkerServerErrorretried once for reads
409, 422KrunkerHttpErrorwrites only

A minimal app

A confidential client on Bun with krapio: sign-in with PKCE and state, the code exchange, reads with a refresh before the token runs out, logout with revocation and signed webhooks. Register an app with the redirect URI http://localhost:8787/callback (it works while the app is in dev mode), then run:

KRUNKER_CLIENT_ID=kapp_... KRUNKER_CLIENT_SECRET=kas_... bun server.ts
import { Krunker, KrunkerOAuthError, KrunkerUnauthorizedError, createPkce, createState, parseCallback, verifyWebhook, type AppSession, type AppWebhookEvent, type OAuthTokens } from "krapio";

const krunker = new Krunker({
    userAgent: "my-app/1.0",
    app: { clientId: process.env.KRUNKER_CLIENT_ID!, clientSecret: process.env.KRUNKER_CLIENT_SECRET!, redirectUri: "http://localhost:8787/callback" },
});

type Stored = OAuthTokens & { expires_at: number };
const pending = new Map<string, string>();  // state -> PKCE verifier
const sessions = new Map<string, Stored>(); // your session id -> tokens
const stamp = (tokens: OAuthTokens): Stored => ({ ...tokens, expires_at: Date.now() + tokens.expires_in * 1000 });

/** the app api for a session, refreshed first when the access token is about to run out */
async function appFor(sid: string): Promise<AppSession> {
    let tokens = sessions.get(sid)!;
    if (Date.now() > tokens.expires_at - 60_000){
        tokens = stamp(await krunker.oauth.refresh(tokens.refresh_token));
        sessions.set(sid, tokens); // the old refresh token is now spent
    }
    return krunker.app(tokens.access_token);
}

Bun.serve({
    port: 8787,
    async fetch(req){
        const url = new URL(req.url);
        const sid = /(?:^|;\s*)sid=([\w-]+)/.exec(req.headers.get("cookie") ?? "")?.[1];

        // 1. send the player to the consent page
        if (url.pathname === "/login"){
            const state = createState();
            const pkce = await createPkce();
            pending.set(state, pkce.verifier);
            return Response.redirect(krunker.oauth.authorizeUrl({ scope: ["profile", "stats:read", "friends:read"], state, codeChallenge: pkce.challenge }), 302);
        }

        // 2. back from Krunker: check state, exchange the code
        if (url.pathname === "/callback"){
            const state = url.searchParams.get("state") ?? "";
            const verifier = pending.get(state);
            pending.delete(state);
            if (!verifier) return new Response("Unknown or expired login attempt", { status: 400 });
            try {
                const callback = parseCallback(url, state);
                if (callback.kind !== "code") return new Response("Not a login", { status: 400 });
                const tokens = await krunker.oauth.exchangeCode({ code: callback.code, codeVerifier: verifier });
                const newSid = createState();
                sessions.set(newSid, stamp(tokens));
                return new Response(null, { status: 302, headers: { Location: "/", "Set-Cookie": `sid=${newSid}; HttpOnly; SameSite=Lax; Path=/` } });
            }
            catch (err){
                if (err instanceof KrunkerOAuthError) return new Response(`Login cancelled: ${err.error}`);
                throw err;
            }
        }

        // 3. log out: revoke the refresh token (and with it the sign-in) and the current access token
        if (url.pathname === "/logout" && req.method === "POST" && sid && sessions.has(sid)){
            const tokens = sessions.get(sid)!;
            sessions.delete(sid);
            await krunker.oauth.revoke(tokens.refresh_token);
            await krunker.oauth.revoke(tokens.access_token);
            return Response.redirect("/", 303);
        }

        // 4. webhooks: 401 for a bad signature, which is also what the Verify check tests
        if (url.pathname === "/webhook" && req.method === "POST"){
            const raw = await req.text();
            if (!await verifyWebhook(raw, req.headers.get("Krunker-Signature"), process.env.KRUNKER_WEBHOOK_SECRET!)){
                return new Response("bad signature", { status: 401 });
            }
            const event = JSON.parse(raw) as AppWebhookEvent;
            if (event.type !== "webhook.verify") console.log(event.id, event.type, event.data);
            return new Response(null, { status: 204 });
        }

        // 5. show the player
        if (url.pathname === "/" && sid && sessions.has(sid)){
            try {
                const me = await appFor(sid);
                const { data: player } = await me.player.me();
                const following = await me.friends.following({ limit: 5 });
                return Response.json({ player, following: following.data });
            }
            catch (err){
                if (!(err instanceof KrunkerUnauthorizedError)) throw err;
                sessions.delete(sid); // disconnected, banned or app suspended
                return Response.redirect("/login", 302);
            }
        }
        return new Response("<a href=\"/login\">Login with Krunker</a>", { headers: { "Content-Type": "text/html" } });
    },
});

Krunker's own document has the same app without a library, on fetch and node:crypto.

On this page