Reseller API · v1

Reseller API documentation

Top up a balance with PIX, buy license keys and track them from your own system. JSON over HTTPS, one Bearer key per integration.

Base URLhttps://evolutionboost.xyz/api/v1

For machines and LLMs:OpenAPI 3.1 llms.txt llms-full.txt api.txt

Introduction

The Evolution Boost Reseller API lets official resellers top up a balance with PIX, buy license keys with that balance and look up their keys (free, redeemed or all) from their own systems, bots or stores.

It is a JSON REST API over HTTPS. The base URL is https://evolutionboost.xyz/api/v1. It is meant for server-to-server use: never call it from a browser or ship your API key inside an app (there is no CORS).

Money is always an integer number of cents of BRL (12990 = R$ 129,90), with currency: "BRL".
Timestamps are ISO 8601 in UTC.
Every response carries an X-Request-Id header. Include it when you contact support.
Responses are never cached (Cache-Control: no-store).
There are no webhooks in v1: poll the endpoints.

Authentication

Authenticate every request with your API key in the Authorization header as a Bearer token. Keys start with evb_live_ and are created by the Evolution Boost team in the admin panel. You receive the full key only once, so store it in a secret manager or environment variable.

A missing, invalid, revoked or expired key returns 401 invalid_api_key (same answer for all cases).
A valid key of a revoked reseller returns 403 reseller_inactive.
Too many authentication failures from the same IP (20 per minute) return 429 before the key is even checked.
If a key leaks, ask the team to revoke it and issue a new one. You can have several keys (for example one per system).

Headers

Header	When	Description
`Authorization`	Always	`Bearer evb_live_...`, your API key.
`Content-Type`	POST	`application/json`. Bodies are limited to 24000 bytes.
`Idempotency-Key`	POST	A unique key per operation (UUID). See Idempotency.
`X-Request-Id`	Optional	Your own request id (8 to 64 characters among `A-Z a-z 0-9 . _ -`), echoed back; otherwise we generate one. Always present in responses.

HTTP

Authorization: Bearer evb_live_xxxxxxxxxxxxxxxx

Errors

Errors use conventional HTTP status codes and a JSON body. Branch on error.type and error.code, never on message. param points to the field or header that caused the error.

Error types

Type	Status	Description
`authentication_error`	401	The API key is missing, invalid, revoked or expired.
`permission_error`	403	The key is valid but the reseller account is not active.
`invalid_request_error`	400, 404, 405, 409, 413	The request is malformed or refers to something that does not exist.
`insufficient_balance`	402	The balance does not cover the purchase. Nothing was charged.
`rate_limit_error`	429	Too many requests. Wait `Retry-After` seconds.
`api_error`	500, 502, 503	Something failed on our side or at the payment provider. Retry with backoff.

Error codes

Code	Status	Description
`invalid_api_key`	401	Missing, invalid, revoked or expired API key. The response is the same for every case.
`reseller_inactive`	403	The reseller account was revoked or removed.
`invalid_json`	400	The body is empty, is not JSON or is not a JSON object.
`idempotency_key_required`	400	POST without the `Idempotency-Key` header.
`invalid_idempotency_key`	400	`Idempotency-Key` must have 1 to 255 visible ASCII characters, no spaces.
`invalid_amount`	400	`amount_cents` must be an integer between 1000 and 500000.
`too_many_pending_deposits`	400	You already have 3 pending deposits. Pay one or wait for it to expire.
`missing_items`	400	Send `items` (non-empty) or `package_code`.
`invalid_items`	400	`items` must be an array of objects.
`too_many_items`	400	`items` accepts at most 50 entries.
`invalid_package_code`	400	`package_code` must look like `H150` (1 to 20 letters or digits).
`invalid_quantity`	400	`quantity` must be an integer between 1 and 100.
`duplicate_package`	400	The same package appears twice in `items`. Merge the quantities.
`too_many_keys`	400	A request can create at most 100 keys in total.
`package_unavailable`	400	The package does not exist or has no wholesale price. See `GET /packages`.
`invalid_limit`	400	`limit` must be an integer between 1 and 100.
`invalid_cursor`	400	`starting_after` is not a UUID or is not an object of this list.
`invalid_status`	400	Unknown value in the `status` filter.
`invalid_kind`	400	Unknown value in the `kind` filter.
`invalid_batch_id`	400	`batch_id` must be a UUID.
`insufficient_balance`	402	The balance does not cover the total of the purchase. Nothing was charged or created.
`resource_missing`	404	The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.
`method_not_allowed`	405	HTTP method not supported. See the `Allow` header.
`idempotency_key_reused`	409	The `Idempotency-Key` was already used with a different body. Use a new key for a new operation.
`payload_too_large`	413	The body is larger than 24000 bytes.
`rate_limit_exceeded`	429	Rate limit reached. Wait the number of seconds in the `Retry-After` header.
`internal_error`	500	Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.
`payment_provider_error`	502	The PIX provider failed to create the charge. Retry later.
`service_unavailable`	503	The service is temporarily unavailable. Retry with backoff.

JSON

{
  "error": {
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "message": "Insufficient balance: this purchase costs 5990 cents and the balance is 1200 cents.",
    "param": null
  },
  "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c"
}

Pagination

List endpoints return {"object": "list", "data": [...], "has_more": bool}, newest first. Use limit (1 to 100, default 20) and, to get the next page, pass the id of the last object you received as starting_after. Stop when has_more is false.

Shell

curl "https://evolutionboost.xyz/api/v1/keys?status=free&limit=100&starting_after=6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b" \
  -H "Authorization: Bearer $EVB_API_KEY"

Idempotency

Every POST that moves money or creates keys requires an Idempotency-Key header. Generate a new UUID for each operation and reuse it only to retry that same operation (timeouts, network errors, 5xx). A retry never charges twice: it returns the original result.

POST /keys retried with the same key and body: 200 with the same batch and the header Idempotent-Replayed: true (the first call returns 201).
POST /deposits retried with the same key and amount: 200 with the same deposit and the same PIX code (no new charge).
Same key with a different body: 409 idempotency_key_reused.
Keys are scoped to your reseller account and do not expire. Never reuse a key for a new operation.

Rate limits

Limits are counted per API key (authentication failures, per IP). Going over returns 429 rate_limit_exceeded with a Retry-After header in seconds. Wait that long before retrying.

Endpoint	Limit
Read endpoints (every GET)	120 per minute, per API key
POST /keys	30 per minute, per API key
POST /deposits	5 per 5 minutes, per API key
Authentication failures	20 per minute, per IP

Quickstart

The recommended flow, from an empty balance to keys in hand:

Check what you can sell and your balance: GET /packages and GET /balance.
Top up: POST /deposits with amount_cents (R$ 10,00 to R$ 5.000,00). Pay the returned br_code (PIX copy-and-paste) or the QR in br_code_base64, then poll GET /deposits/{id} every 5 to 10 seconds until status is paid.
Buy keys: POST /keys with items and a fresh Idempotency-Key. The response has the full text of every key.
Track them: GET /keys?status=free (not redeemed yet) or GET /keys?status=redeemed.

Shell

export EVB_API_KEY="evb_live_..."

# 1. Packages and balance
curl https://evolutionboost.xyz/api/v1/packages -H "Authorization: Bearer $EVB_API_KEY"
curl https://evolutionboost.xyz/api/v1/balance -H "Authorization: Bearer $EVB_API_KEY"

# 2. Deposit R$ 500,00, pay the PIX, poll until "paid"
curl -X POST https://evolutionboost.xyz/api/v1/deposits \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount_cents": 50000}'
curl https://evolutionboost.xyz/api/v1/deposits/9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b -H "Authorization: Bearer $EVB_API_KEY"

# 3. Buy 10 keys of H150
curl -X POST https://evolutionboost.xyz/api/v1/keys \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"package_code": "H150", "quantity": 10}]}'

# 4. Keys not redeemed yet
curl "https://evolutionboost.xyz/api/v1/keys?status=free" -H "Authorization: Bearer $EVB_API_KEY"

API reference

Me

Who you are: reseller, API key in use and balance. A good first call to test your integration.

The Reseller object

The reseller that owns the API key.

objectstring (reseller)
Always reseller.
idstring
Reseller id.
namestring
Display name.
codestring
Reseller code. It is the first part of the keys you buy.
statusstring (active | revoked)
Only active resellers can call the API.
tokenTokenInfo
The API key used in this request.
balanceBalance
Current balance.

Endpoints

GET/v1/me

The Reseller object

{
  "object": "reseller",
  "id": "5f0c2a3e-8d41-4b6a-9e2f-1c7d3b9a6e10",
  "name": "ACME Games",
  "code": "ACME",
  "status": "active",
  "token": {
    "name": "Store backend",
    "prefix": "xxxxxxxx"
  },
  "balance": {
    "object": "balance",
    "balance_cents": 125000,
    "currency": "BRL",
    "updated_at": "2026-10-17T14:10:03.000Z"
  }
}

Retrieve the reseller

GET/v1/me

Returns the reseller that owns the API key, the key used and the current balance.

Rate limit: 120 per minute, per API key

Responses

200The reseller.

Errors

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl https://evolutionboost.xyz/api/v1/me \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "reseller",
  "id": "5f0c2a3e-8d41-4b6a-9e2f-1c7d3b9a6e10",
  "name": "ACME Games",
  "code": "ACME",
  "status": "active",
  "token": {
    "name": "Store backend",
    "prefix": "xxxxxxxx"
  },
  "balance": {
    "object": "balance",
    "balance_cents": 125000,
    "currency": "BRL",
    "updated_at": "2026-10-17T14:10:03.000Z"
  }
}

API reference

Packages

Plans available to resellers, with your wholesale price.

The Package object

A plan you can buy keys for, with your wholesale price.

objectstring (package)
Always package.
codestring
Package code used in POST /keys (for example H150).
hoursinteger
Farming hours granted by one key.
account_limitinteger
Steam accounts the customer can farm at the same time.
price_centsinteger
Your wholesale price per key, in cents of BRL.
currencystring (BRL)
Always BRL.

Endpoints

GET/v1/packages

The Package object

{
  "object": "package",
  "code": "H150",
  "hours": 150,
  "account_limit": 3,
  "price_cents": 499,
  "currency": "BRL"
}

List packages

GET/v1/packages

Lists the packages you can buy keys for, with your wholesale price per key. Packages without a wholesale price are not listed and cannot be bought. Not paginated (has_more is always false).

Rate limit: 120 per minute, per API key

Responses

200The list of packages.

Errors

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl https://evolutionboost.xyz/api/v1/packages \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "list",
  "data": [
    {
      "object": "package",
      "code": "H150",
      "hours": 150,
      "account_limit": 3,
      "price_cents": 499,
      "currency": "BRL"
    },
    {
      "object": "package",
      "code": "H600",
      "hours": 600,
      "account_limit": 6,
      "price_cents": 1099,
      "currency": "BRL"
    },
    {
      "object": "package",
      "code": "H1200",
      "hours": 1200,
      "account_limit": 12,
      "price_cents": 1899,
      "currency": "BRL"
    }
  ],
  "has_more": false
}

API reference

Balance

Your prepaid balance in BRL. Deposits credit it; key purchases debit it.

The Balance object

The current wallet balance of the reseller.

objectstring (balance)
Always balance.
balance_centsinteger
Available balance in cents of BRL.
currencystring (BRL)
Always BRL.
updated_atstring | null
Last balance change; null if the wallet was never used.

Endpoints

GET/v1/balance

The Balance object

{
  "object": "balance",
  "balance_cents": 125000,
  "currency": "BRL",
  "updated_at": "2026-10-17T14:10:03.000Z"
}

Retrieve the balance

GET/v1/balance

Returns the current balance of your wallet, in cents of BRL.

Rate limit: 120 per minute, per API key

Responses

200The balance.

Errors

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl https://evolutionboost.xyz/api/v1/balance \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "balance",
  "balance_cents": 125000,
  "currency": "BRL",
  "updated_at": "2026-10-17T14:10:03.000Z"
}

API reference

Ledger

Every balance movement, immutable, with the balance after each one.

The LedgerEntry object

An immutable balance movement.

objectstring (ledger_entry)
Always ledger_entry.
idstring
Entry id (also the pagination cursor).
kindstring (deposit | key_purchase | adjustment | refund)
deposit (PIX paid), key_purchase (keys bought), adjustment (manual, by the Evolution Boost team) or refund.
amount_centsinteger
Signed amount: positive credits, negative debits.
balance_after_centsinteger
Balance right after this movement.
currencystring (BRL)
Always BRL.
ref_typestring | null
What originated it, for example deposit or key_batch; usually null for adjustments.
ref_idstring | null
Id of the deposit or of the key batch.
descriptionstring | null
Short human-readable description (may be in Portuguese).
created_atstring
When the movement happened.

Endpoints

GET/v1/ledger

The LedgerEntry object

{
  "object": "ledger_entry",
  "id": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a",
  "kind": "key_purchase",
  "amount_cents": -5990,
  "balance_after_cents": 125000,
  "currency": "BRL",
  "ref_type": "key_batch",
  "ref_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
  "description": "10x H150, 1x H600",
  "created_at": "2026-10-17T14:10:03.000Z"
}

List ledger entries

GET/v1/ledger

Lists balance movements, newest first. Paginated.

Rate limit: 120 per minute, per API key

Parameters

limitquery · integerOptional
Number of objects to return, between 1 and 100. Default 20.
starting_afterquery · stringOptional
Cursor: the id of the last object of the previous page. Returns the objects that come after it.
kindquery · string (deposit | key_purchase | adjustment | refund)Optional
Only movements of this kind.

Responses

200A page of ledger entries.

Errors

400invalid_limit limit must be an integer between 1 and 100.
400invalid_cursor starting_after is not a UUID or is not an object of this list.
400invalid_kind Unknown value in the kind filter.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl "https://evolutionboost.xyz/api/v1/ledger?kind=key_purchase&limit=20" \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "list",
  "data": [
    {
      "object": "ledger_entry",
      "id": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a",
      "kind": "key_purchase",
      "amount_cents": -5990,
      "balance_after_cents": 125000,
      "currency": "BRL",
      "ref_type": "key_batch",
      "ref_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "description": "10x H150, 1x H600",
      "created_at": "2026-10-17T14:10:03.000Z"
    },
    {
      "object": "ledger_entry",
      "id": "2e3f4a5b-6c7d-4e8f-a9b0-c1d2e3f4a5b6",
      "kind": "deposit",
      "amount_cents": 50000,
      "balance_after_cents": 130990,
      "currency": "BRL",
      "ref_type": "deposit",
      "ref_id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
      "description": "Deposito PIX",
      "created_at": "2026-10-17T14:02:41.000Z"
    }
  ],
  "has_more": true
}

API reference

Deposits

PIX charges that credit your balance. From R$ 10,00 to R$ 5.000,00 each, at most 3 pending at a time.

The Deposit object

A PIX charge that credits your balance once paid.

objectstring (deposit)
Always deposit.
idstring
Deposit id.
amount_centsinteger
Amount in cents of BRL.
currencystring (BRL)
Always BRL.
statusstring (pending | paid | failed | expired)
pending until the PIX is paid; paid means the balance was credited; failed or expired will never be credited.
br_codestring | null
PIX copy-and-paste code. Only while pending.
br_code_base64string | null
QR code as a PNG data URL (data:image/png;base64,...). Only while pending.
expires_atstring | null
When the PIX charge expires (set by the payment provider).
created_atstring
Creation time.
paid_atstring | null
When the payment was confirmed.

Endpoints

POST/v1/deposits
GET/v1/deposits/{id}
GET/v1/deposits

The Deposit object

{
  "object": "deposit",
  "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
  "amount_cents": 50000,
  "currency": "BRL",
  "status": "pending",
  "br_code": "00020101021226850014br.gov.bcb.pix...6304A1B2",
  "br_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2026-10-18T14:00:00.000Z",
  "created_at": "2026-10-17T14:00:00.000Z",
  "paid_at": null
}

Create a deposit

POST/v1/deposits

Creates a PIX charge for amount_cents. Pay br_code (copy-and-paste) or the QR in br_code_base64; the balance is credited automatically once the payment is confirmed. Then poll GET /deposits/{id}. At most 3 pending deposits at a time.

Rate limit: 5 per 5 minutes, per API keyRequires Idempotency-Key

Parameters

Idempotency-Keyheader · stringRequired
Unique key per operation (a UUID is ideal), 1 to 255 visible ASCII characters. Retrying with the same key never charges twice.

Body

amount_centsintegerRequired
Amount in cents of BRL, from 1000 (R$ 10,00) to 500000 (R$ 5.000,00).

Responses

200The pending deposit with the PIX code. A retry with the same Idempotency-Key returns the same deposit.

Errors

400idempotency_key_required POST without the Idempotency-Key header.
400invalid_idempotency_key Idempotency-Key must have 1 to 255 visible ASCII characters, no spaces.
400invalid_json The body is empty, is not JSON or is not a JSON object.
400invalid_amount amount_cents must be an integer between 1000 and 500000.
400too_many_pending_deposits You already have 3 pending deposits. Pay one or wait for it to expire.
409idempotency_key_reused The Idempotency-Key was already used with a different body. Use a new key for a new operation.
413payload_too_large The body is larger than 24000 bytes.
502payment_provider_error The PIX provider failed to create the charge. Retry later.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl -X POST https://evolutionboost.xyz/api/v1/deposits \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount_cents":50000}'

Response · 200

{
  "object": "deposit",
  "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
  "amount_cents": 50000,
  "currency": "BRL",
  "status": "pending",
  "br_code": "00020101021226850014br.gov.bcb.pix...6304A1B2",
  "br_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2026-10-18T14:00:00.000Z",
  "created_at": "2026-10-17T14:00:00.000Z",
  "paid_at": null
}

Retrieve a deposit

GET/v1/deposits/{id}

Returns a deposit. While it is pending, this call also checks the payment with the PIX provider, so polling it every 5 to 10 seconds is how you learn that the balance was credited. A deposit of another reseller returns 404.

Rate limit: 120 per minute, per API key

Parameters

idpath · stringRequired
Deposit id.

Responses

200The deposit.

Errors

404resource_missing The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl https://evolutionboost.xyz/api/v1/deposits/9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "deposit",
  "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
  "amount_cents": 50000,
  "currency": "BRL",
  "status": "paid",
  "br_code": null,
  "br_code_base64": null,
  "expires_at": "2026-10-18T14:00:00.000Z",
  "created_at": "2026-10-17T14:00:00.000Z",
  "paid_at": "2026-10-17T14:02:41.000Z"
}

List deposits

GET/v1/deposits

Lists your deposits, newest first. Paginated. Unlike GET /deposits/{id}, the list does not check pending payments with the provider.

Rate limit: 120 per minute, per API key

Parameters

limitquery · integerOptional
Number of objects to return, between 1 and 100. Default 20.
starting_afterquery · stringOptional
Cursor: the id of the last object of the previous page. Returns the objects that come after it.
statusquery · string (pending | paid | failed | expired)Optional
Only deposits with this status.

Responses

200A page of deposits.

Errors

400invalid_limit limit must be an integer between 1 and 100.
400invalid_cursor starting_after is not a UUID or is not an object of this list.
400invalid_status Unknown value in the status filter.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl "https://evolutionboost.xyz/api/v1/deposits?status=paid&limit=20" \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "list",
  "data": [
    {
      "object": "deposit",
      "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b",
      "amount_cents": 50000,
      "currency": "BRL",
      "status": "paid",
      "br_code": null,
      "br_code_base64": null,
      "expires_at": "2026-10-18T14:00:00.000Z",
      "created_at": "2026-10-17T14:00:00.000Z",
      "paid_at": "2026-10-17T14:02:41.000Z"
    },
    {
      "object": "deposit",
      "id": "3c8f1a20-6b7d-4e9f-8a1b-2c3d4e5f6a7b",
      "amount_cents": 100000,
      "currency": "BRL",
      "status": "paid",
      "br_code": null,
      "br_code_base64": null,
      "expires_at": "2026-10-11T09:00:00.000Z",
      "created_at": "2026-10-10T09:00:00.000Z",
      "paid_at": "2026-10-10T09:01:15.000Z"
    }
  ],
  "has_more": false
}

API reference

Keys

Buy license keys with your balance and look up the keys you own.

The Key object

A license key that belongs to you.

objectstring (key)
Always key.
idstring
Key id (also the pagination cursor).
keystring | null
Full key text. null for old keys that cannot be recovered (use key_prefix).
key_prefixstring
First three parts of the key, safe to show.
package_codestring
Package of the key.
hoursinteger | null
Hours granted by the key.
statusstring (free | redeemed | revoked | suspended)
free (not redeemed yet), redeemed, revoked or suspended.
batch_idstring | null
Purchase batch that created the key.
created_atstring
Creation time.
redeemed_atstring | null
When a customer redeemed it.

Endpoints

POST/v1/keys
GET/v1/keys
GET/v1/keys/{id}

The Key object

{
  "object": "key",
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
  "key_prefix": "ACME-H150-AAAA",
  "package_code": "H150",
  "hours": 150,
  "status": "free",
  "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
  "created_at": "2026-10-17T14:10:03.000Z",
  "redeemed_at": null
}

Buy keys

POST/v1/keys

Debits the wholesale price from your balance and creates the keys in one atomic operation. If the balance is not enough, nothing is charged or created (402 insufficient_balance). Up to 100 keys and 50 items per request. The response contains the full text of every key.

Rate limit: 30 per minute, per API keyRequires Idempotency-Key

Parameters

Idempotency-Keyheader · stringRequired
Unique key per operation (a UUID is ideal), 1 to 255 visible ASCII characters. Retrying with the same key never charges twice.

Body

itemsPurchaseItem[]Required
What to buy: 1 to 50 objects {package_code, quantity}, each package at most once.
items[].package_codestringRequired
Package code from GET /packages.
items[].quantityintegerOptional
Number of keys, 1 to 100. Default 1.

For a single package you can also send {"package_code": "H150", "quantity": 10} instead of items.

Responses

201The batch was bought.
200Retry with the same Idempotency-Key and body: the original batch, nothing charged again.Idempotent-Replayed: true when the response is a replay.

Errors

400idempotency_key_required POST without the Idempotency-Key header.
400invalid_idempotency_key Idempotency-Key must have 1 to 255 visible ASCII characters, no spaces.
400invalid_json The body is empty, is not JSON or is not a JSON object.
400missing_items Send items (non-empty) or package_code.
400invalid_items items must be an array of objects.
400too_many_items items accepts at most 50 entries.
400invalid_package_code package_code must look like H150 (1 to 20 letters or digits).
400invalid_quantity quantity must be an integer between 1 and 100.
400duplicate_package The same package appears twice in items. Merge the quantities.
400too_many_keys A request can create at most 100 keys in total.
400package_unavailable The package does not exist or has no wholesale price. See GET /packages.
402insufficient_balance The balance does not cover the total of the purchase. Nothing was charged or created.
409idempotency_key_reused The Idempotency-Key was already used with a different body. Use a new key for a new operation.
413payload_too_large The body is larger than 24000 bytes.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl -X POST https://evolutionboost.xyz/api/v1/keys \
  -H "Authorization: Bearer $EVB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items":[{"package_code":"H150","quantity":2},{"package_code":"H600","quantity":1}]}'

Response · 201

{
  "object": "key_batch",
  "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
  "total_cents": 2097,
  "balance_cents": 122903,
  "currency": "BRL",
  "keys": [
    {
      "object": "key",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
      "key_prefix": "ACME-H150-AAAA",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    },
    {
      "object": "key",
      "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b",
      "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB",
      "key_prefix": "ACME-H150-BBBB",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    },
    {
      "object": "key",
      "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e",
      "key": "ACME-H600-CCCC-CCCC-CCCC-CCCC",
      "key_prefix": "ACME-H600-CCCC",
      "package_code": "H600",
      "hours": 600,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    }
  ]
}

List keys

GET/v1/keys

Lists your keys, newest first. Paginated. Filter by status (free = not redeemed yet), package or purchase batch. Responses that include the key text are audited.

Rate limit: 120 per minute, per API key

Parameters

limitquery · integerOptional
Number of objects to return, between 1 and 100. Default 20.
starting_afterquery · stringOptional
Cursor: the id of the last object of the previous page. Returns the objects that come after it.
statusquery · string (free | redeemed | all)Optional
free (not redeemed), redeemed or all (default; also includes revoked and suspended keys).
package_codequery · stringOptional
Only keys of this package.
batch_idquery · stringOptional
Only keys of this purchase batch.

Responses

200A page of keys.

Errors

400invalid_limit limit must be an integer between 1 and 100.
400invalid_cursor starting_after is not a UUID or is not an object of this list.
400invalid_status Unknown value in the status filter.
400invalid_package_code package_code must look like H150 (1 to 20 letters or digits).
400invalid_batch_id batch_id must be a UUID.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl "https://evolutionboost.xyz/api/v1/keys?status=free&package_code=H150&limit=50" \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "list",
  "data": [
    {
      "object": "key",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
      "key_prefix": "ACME-H150-AAAA",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    },
    {
      "object": "key",
      "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b",
      "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB",
      "key_prefix": "ACME-H150-BBBB",
      "package_code": "H150",
      "hours": 150,
      "status": "free",
      "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
      "created_at": "2026-10-17T14:10:03.000Z",
      "redeemed_at": null
    }
  ],
  "has_more": true
}

Retrieve a key

GET/v1/keys/{id}

Returns one key by its id (UUID). To check whether a key you sold was redeemed, take its id from GET /keys: the key text never goes in the URL, where proxies and logs could record it. A key of another reseller, an unknown id or a malformed value all return the same 404. Responses that include the key text are audited.

Rate limit: 120 per minute, per API key

Parameters

idpath · stringRequired
Key id (UUID), as returned by GET /keys or POST /keys.

Responses

200The key.

Errors

404resource_missing The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.

Every endpoint can also return: invalid_api_key, reseller_inactive, rate_limit_exceeded, method_not_allowed, internal_error, service_unavailable.

Request

curl https://evolutionboost.xyz/api/v1/keys/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $EVB_API_KEY"

Response · 200

{
  "object": "key",
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA",
  "key_prefix": "ACME-H150-AAAA",
  "package_code": "H150",
  "hours": 150,
  "status": "redeemed",
  "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21",
  "created_at": "2026-10-17T14:10:03.000Z",
  "redeemed_at": "2026-10-17T18:22:09.000Z"
}