Successful mints on a contract by NimbusMint users from your app

GET

/hits

curl -G "https://api.nimbusmint.bot/partner/v1/hits" \
  -H "Authorization: Bearer $NIMBUS_PRIVATE_KEY" \
  --data-urlencode "contract=0x000000000000000000000000000000000000dead" \
  --data-urlencode "since=2026-10-08T15:00:00Z"

// Node 18+ (built-in fetch). Keep the key on your server.
const url = new URL('https://api.nimbusmint.bot/partner/v1/hits');
url.search = new URLSearchParams({
  contract: '0x000000000000000000000000000000000000dead',
  since: '2026-10-08T15:00:00Z',
});
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_PRIVATE_KEY}` },
});
console.log(res.status, await res.json());

import os
import requests

res = requests.get(
    "https://api.nimbusmint.bot/partner/v1/hits",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_PRIVATE_KEY']}"},
    params={
        "contract": "0x000000000000000000000000000000000000dead",
        "since": "2026-10-08T15:00:00Z",
    },
    timeout=10,
)
print(res.status_code, res.json())

Counts hits on one contract in a window. A hit is one mint task that completed successfully (receipt confirmed, not reverted) and that was booked through your app, timed by when it completed. It is not a token count: a task that minted three tokens is one hit. Failed, reverted and cancelled tasks never count, and nor do tasks booked before your app’s attribution went live.

Users are distinct NimbusMint accounts. Each listed user carries their full identity: user_id, discord_id, discord_username and the wallets their hits in the window minted from. These are your users’ personal data: mask them yourself before showing them to anyone else. handle is a ready-masked form (the first character of their name and seven *). users is ranked by hits, then by most recent hit; others sums everyone beyond top, so total = users

others. For every individual hit, use /mints.

gas is the user’s settings on their most recent hit in the window: manual with the max fee and priority fee in gwei, or auto (fees chosen by the network at send time) with nulls.

Answers are cached for cache_ttl_s seconds; since and until are floored to the minute.

Requires scope read:hits.

Errors

Status	`code`	Meaning
400	`window_too_large`	The query is invalid (`invalid_request`) or the window is longer than allowed (`window_too_large`).
400	`invalid_request`	The query is invalid (`invalid_request`) or the window is longer than allowed (`window_too_large`).
401	`invalid_key`	The key is missing, malformed, unknown, expired or revoked, or its partner is disabled. Always `invalid_key`.
403	`ip_not_allowed`	The calling address is not on the key’s allowlist (`ip_not_allowed`), or the key lacks the route’s scope (`scope_missing`).
403	`scope_missing`	The calling address is not on the key’s allowlist (`ip_not_allowed`), or the key lacks the route’s scope (`scope_missing`).
429	`rate_limited`	The key’s rate limit, or the API’s overall limit, is exceeded (`rate_limited`).
503	`tenant_api_disabled`	The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon.
503	`ip_trust_unconfigured`	The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon.
503	`internal`	The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon.

What to do about each: Errors.

Authorizations

privateKey

Parameters

Query Parameters

contract

required

string

/^0x[0-9a-fA-F]{40}$/

Contract address, 0x-prefixed, any case.

Example

0x000000000000000000000000000000000000dead

since

required

string format: date-time

Window start (inclusive), RFC 3339.

Example

2026-10-08T15:00:00Z

until

string format: date-time

Window end (exclusive), RFC 3339. Defaults to now; a future time is clamped to now. The window may span at most 31 days unless your agreement sets another limit (window_too_large).

chain_id

integer

>= 1

Only this chain. Omitted, every chain is counted and chain_ids lists those that matched.

Example

top

integer

default: 25 >= 1 <= 50

How many users to list individually.

Responses

200

Hits in the window.

application/json

object

contract

required

The contract, lowercased.

string

chain_ids

required

Chains with at least one hit, ascending.

Array<integer>

since

required

string format: date-time

until

required

string format: date-time

total

required

object

hits

required

integer

users

required

Distinct NimbusMint accounts.

integer

users

required

Array<object>

object

handle

required

First character of the user’s name and seven *. Not unique.

string

user_id

required

The NimbusMint account id. Stable; today it equals the Discord id.

string

discord_id

required

The user’s Discord id; empty if the account record is missing.

string

discord_username

required

The user’s Discord username as last seen at login; empty if unknown.

string

wallets

required

Distinct wallet addresses (lowercase, ascending) the user’s hits in the window minted from.

Array<string>

hits

required

integer

gas

required

object

mode

required

string

Allowed values: manual auto

max_fee_gwei

required

Max fee per gas in gwei, decimal string; null when auto.

string | null

priority_gwei

required

Priority fee per gas in gwei, decimal string; null when auto or not set.

string | null

others

required

object

users

required

integer

hits

required

integer

generated_at

required

string format: date-time

cache_ttl_s

required

Seconds this answer is cached for.

integer

Examples

hits

A collection with one auto-gas user and a tail

{
  "contract": "0x000000000000000000000000000000000000dead",
  "chain_ids": [
    33139
  ],
  "since": "2026-10-08T15:00:00Z",
  "until": "2026-10-08T18:42:00Z",
  "total": {
    "hits": 36,
    "users": 11
  },
  "users": [
    {
      "handle": "a*******",
      "user_id": "100000000000000001",
      "discord_id": "100000000000000001",
      "discord_username": "alice",
      "wallets": [
        "0x1111111111111111111111111111111111111111"
      ],
      "hits": 9,
      "gas": {
        "mode": "manual",
        "max_fee_gwei": "3",
        "priority_gwei": "0.5"
      }
    },
    {
      "handle": "b*******",
      "user_id": "100000000000000002",
      "discord_id": "100000000000000002",
      "discord_username": "bob",
      "wallets": [
        "0x2222222222222222222222222222222222222222",
        "0x3333333333333333333333333333333333333333"
      ],
      "hits": 7,
      "gas": {
        "mode": "auto",
        "max_fee_gwei": null,
        "priority_gwei": null
      }
    }
  ],
  "others": {
    "users": 9,
    "hits": 20
  },
  "generated_at": "2026-10-08T18:42:07Z",
  "cache_ttl_s": 30
}

400

The query is invalid (invalid_request) or the window is longer than allowed (window_too_large).

application/json

object

code

required

string

Allowed values: invalid_key ip_not_allowed scope_missing rate_limited ip_trust_unconfigured tenant_api_disabled invalid_request window_too_large not_found internal

message

required

string

Examples

window

{
  "code": "window_too_large",
  "message": "the window may span at most 31 days"
}

401

The key is missing, malformed, unknown, expired or revoked, or its partner is disabled. Always invalid_key.

application/json

object

code

required

string

Allowed values: invalid_key ip_not_allowed scope_missing rate_limited ip_trust_unconfigured tenant_api_disabled invalid_request window_too_large not_found internal

message

required

string

Examples

invalid

{
  "code": "invalid_key",
  "message": "missing, invalid, expired or revoked key"
}

403

The calling address is not on the key’s allowlist (ip_not_allowed), or the key lacks the route’s scope (scope_missing).

application/json

object

code

required

string

Allowed values: invalid_key ip_not_allowed scope_missing rate_limited ip_trust_unconfigured tenant_api_disabled invalid_request window_too_large not_found internal

message

required

string

Examples

{
  "code": "ip_not_allowed",
  "message": "this address may not use this key"
}

429

The key’s rate limit, or the API’s overall limit, is exceeded (rate_limited).

application/json

object

code

required

string

Allowed values: invalid_key ip_not_allowed scope_missing rate_limited ip_trust_unconfigured tenant_api_disabled invalid_request window_too_large not_found internal

message

required

string

Examples

limited

{
  "code": "rate_limited",
  "message": "rate limit exceeded"
}

Headers

Retry-After

integer

>= 1

Seconds to wait before retrying.

503

The API is switched off (tenant_api_disabled), not configured (ip_trust_unconfigured) or temporarily unable to answer (internal). Retry later; Retry-After is sent when a retry is expected to succeed soon.

application/json

object

code

required

string

Allowed values: invalid_key ip_not_allowed scope_missing rate_limited ip_trust_unconfigured tenant_api_disabled invalid_request window_too_large not_found internal

message

required

string

Examples

disabled

{
  "code": "tenant_api_disabled",
  "message": "the partner API is disabled"
}

Headers

Retry-After

integer

>= 1

Seconds to wait before retrying.