Cytrongift API live
↑↓ move↵ openesc close
Updated: 12 Nov 2026

Cytrongift API v1.5.4

Browse the buy-back catalogue, sell gift cards and game keys, request payouts and manage your Cytrongift account through a JSON API.

Add the Cytrongift API to my app: api.cytrongift.com/SKILL.md

Paste this into your coding assistant: it gets the signing rules, endpoints, errors and clients from SKILL.md.

Explore the API

Base address

https://api.cytrongift.com/v1

Add any endpoint path below to this URL. The same API with test money lives at https://sandbox.cytrongift.com/v1, see Sandbox.

Envelope

Successful requests return { "ok": 1, "data": { } }. Errors return { "ok": 0, "error": { "id": "3003", "code": 401, "desc": "", "advice": "", "extra": { } } }.

error.code matches the HTTP status. desc explains what went wrong; advice tells you what to do next. Both follow Accept-Language; use ru for Russian. Error ids fall into three groups: 3xxx for authentication and limits, 4xxx for business rules, and 5xxx for transport and service errors.

Authentication

Start in Apps & API in your Cytrongift account. Request access, wait for the approval email, then create a key. You get a public Key ID (ck_...) and a Secret (cs_...). The secret is shown only once.

To sign a request, send these three headers:

X-Api-Key: ck_...
X-Timestamp: 1788605154
X-Signature: hex( hmac_sha256( METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + RAW_BODY, secret ) )

You can also call POST /auth with a signed request to get a Bearer token. Send it as Authorization: Bearer ... on endpoints that accept either authentication method. The token lasts up to a day and stays linked to the application that created it.

A first-party application that signs its members in on its own server (a Telegram Mini App, for example) calls POST /auth/identity and receives a user token pair (ut_... and rt_...) for one member; every call with that token acts as that member and carries the application's scopes except identity:assert. A new member signs in with an e-mail address first: POST /auth/identity with create: false, then POST /auth/identity/claim mails a code and POST /auth/identity/claim/confirm turns it into the token pair. A member without a confirmed e-mail address can read everything, but POST /sell/cards, POST /sell/games and POST /withdrawal/create answer 403 with error 4086 until the address from POST /account/email is confirmed.

Each application has a set of approved scopes. Check the scope listed for the endpoint you want to call. Without it, the request returns 3014. A paused or disabled application returns 3013; a revoked or expired key returns 3012.

Limits

The default limit is 60 requests per minute. An application can have a higher limit (a first-party application up to 6000); requests are counted per key, before authentication. A request with a user token also counts against that member's own limit of 60 a minute, and the X-RateLimit-* headers report whichever budget has fewer requests left. Exceed the limit and you get HTTP 429, error 3011, and a Retry-After header. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds left in the current minute), so a client can pace itself before the refusal.

During maintenance, every endpoint except /health returns HTTP 503 with error 5008.

Content types and pagination

For POST and PATCH, send application/json; an unsupported content type returns 4000. The exception is POST /uploads/images, which takes multipart/form-data. GET requests need no Content-Type.

List endpoints use cursor pagination: ?cursor=123&limit=20. The response includes items, limit, cursor, next_cursor and filters. Use next_cursor for the next page; null means you have reached the end. Catalogue lists run from lower to higher ids. Account and withdrawal lists run from higher to lower ids.

Webhooks

Register up to 5 https addresses with POST /account/webhooks; the answer shows the secret once. Each finished sale or payout and each decision on your application is delivered as one JSON POST: event (order.completed, order.rejected, withdrawal.completed, withdrawal.rejected, application.approved, application.rejected, application.paused), entity, id, status, amount and currency for money events, name and reason for application events, user_id and at. The headers X-Event and X-Delivery-Id repeat the event and the delivery number; X-Signature is hmac_sha256(body, secret) in hex. Verify it before you act.

Answer 2xx within 10 seconds. A 5xx, a timeout or a connection failure is retried with growing delays, 5 attempts at most; a 410 switches the address off; any other 4xx drops that delivery. Deliveries are at least once: keep the delivery id and skip one you have already handled.

Money

Amounts use the site currency (USD), with up to two decimal places. Catalogue prices are different: each price uses the item's currency_id. To convert it to a payout in site currency, use price / payments[currency_id].rate.

Sandbox

https://sandbox.cytrongift.com/v1

The same API against a separate database with test money: every path, envelope, signature rule and error id is the one above. Only the address and the key differ, so a client built here runs on the live address after a change of base URL and key pair.

Get access

  1. Open Apps & API in your Cytrongift account and request API access, exactly as for the live API. One approval covers both addresses.
  2. Once the application is approved, press Sandbox key on the same page. You get a Key ID that starts with cks_ and a Secret (cs_...) shown once; the live key stays separate.
  3. Point your client at the sandbox address and sign requests the usual way. The example clients take the base URL as their first argument:
CYTRON_API_KEY=cks_... CYTRON_API_SECRET=cs_... php client.php https://sandbox.cytrongift.com/v1
  1. Call GET /health: on the sandbox it reports "sandbox": true, and every sandbox answer carries the header X-Sandbox: 1.

What is different

AreaOn the sandbox
BalanceEvery account starts with 1000 USD of test money. No money moves and nothing is reviewed by a person.
Orders and payoutsSettled by the sandbox itself two minutes after creation: most complete, every third is rejected, so both outcomes can be rehearsed.
CatalogueBrands, platforms, cards, keys, payout methods and prices are a daily copy of the live ones; icons and other file links point at the live site.
Account dataMembers, orders and payouts of the live site are never there; the sandbox account is a twin with the same ID.
WebhooksThe same deliveries as on the live API, signed the same way, with one more header: X-Sandbox: 1.
Limits60 requests a minute, not raised. Uploads, tokens and the rest of the account endpoints work as on the live address.

Reference

Each endpoint includes a signed request example in curl, PHP, JavaScript, Python and Go. Pick your language once; it applies across the page.

Service

Check service health, read configuration and look up bonus tiers.

Checks the database and cache. Returns 200 when both respond, or 503 if either check fails.

GEThttps://api.cytrongift.com/v1/health

Request

curl https://api.cytrongift.com/v1/health

Response

{
    "ok": 1,
    "data": {
        "status": "ok",
        "service": "cytrongift-api",
        "version": "1.5.4",
        "sandbox": false,
        "timestamp": 1788605154,
        "checks": {
            "database": "ok",
            "cache": "ok"
        }
    }
}

Returns service metadata, the allowed values used by write endpoints, and public website links. The links object includes support, developer, blog and agreement URLs for each language. links.news repeats links.blog for clients built on the old name; it is removed in a later release.

GEThttps://api.cytrongift.com/v1/config

Request

curl https://api.cytrongift.com/v1/config

Response

{
    "ok": 1,
    "data": {
        "service": "cytrongift-api",
        "version": "1.5.4",
        "currency_code": "USD",
        "currency_symbol": "$",
        "languages": [
            "en",
            "ru"
        ],
        "card_types": {
            "ALL": 0,
            "ECODE": 1,
            "PCARD": 2
        },
        "order_status": {
            "PROCESSING": 0,
            "COMPLETE": 1,
            "REJECTED": 2,
            "UNDER_REVIEW": 3
        },
        "signature_window": 300,
        "rate_limit_minute": 60,
        "timestamp": 1788605157,
        "links": {
            "support": "https://cytrongift.com/en/support/",
            "developer": "https://api.cytrongift.com/docs/",
            "blog": {
                "en": "https://cytrongift.com/en/blog/",
                "ru": "https://cytrongift.com/ru/blog/"
            },
            "news": {
                "en": "https://cytrongift.com/en/blog/",
                "ru": "https://cytrongift.com/ru/blog/"
            },
            "agreement": {
                "en": "https://cytrongift.com/en/pages/terms.html",
                "ru": "https://cytrongift.com/ru/pages/terms.html"
            }
        }
    }
}

Returns the public table of bonus tiers.

GEThttps://api.cytrongift.com/v1/bonus

Request

curl https://api.cytrongift.com/v1/bonus

Response

{
    "ok": 1,
    "data": {
        "levels": [
            {
                "level": 1,
                "threshold": 10000,
                "bonus_percent": 0.05
            }
        ]
    }
}

Returns the public counters of the service, counted from the database and refreshed at most once an hour: card_types (the live cards and games a seller can choose now), members (confirmed accounts that may sign in), items_sold (the quantity of items in completed orders) and referral_rewards (the lifetime referral credits paid to members, a number in USD with two decimals), plus currency and symbol. No credentials are needed.

GEThttps://api.cytrongift.com/v1/stats

Request

curl https://api.cytrongift.com/v1/stats

Response

{
    "ok": 1,
    "data": {
        "card_types": 120,
        "members": 25000,
        "items_sold": 98000,
        "referral_rewards": 14250.5,
        "currency": "USD",
        "symbol": "$"
    }
}

Lists the 10 most recent completed sales, anonymous. Each item has id (an opaque hash), kind (card or game), item_id, name_en, name_ru, amount (a number in USD), sold_at (ISO 8601 UTC) and has_image; when has_image is true the logo is at /catalog/images?kind=<kind>&id=<item_id>. No credentials are needed.

GEThttps://api.cytrongift.com/v1/sales/latest

Request

curl https://api.cytrongift.com/v1/sales/latest

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": "9f2c0e5d1b7a4c3e8d6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
                "kind": "card",
                "item_id": 42,
                "name_en": "Apple Gift Card US",
                "name_ru": "Apple Gift Card US",
                "amount": 48.5,
                "sold_at": "2026-11-06T09:30:00Z",
                "has_image": true
            }
        ],
        "currency": "USD",
        "symbol": "$"
    }
}

Catalogue

Browse the cards and game keys we buy, plus the available payout methods. These endpoints are public.

Lists brands with at least one gift card currently accepted for sale. Each item includes id, name_ru, name_en, icon and sort. The icon is an absolute URL, or an empty string if no icon is set.

GEThttps://api.cytrongift.com/v1/catalog/brands

Request

curl https://api.cytrongift.com/v1/catalog/brands

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": 1,
                "name_ru": "Amazon",
                "name_en": "Amazon",
                "icon": "https://cytrongift.com/uploads/brands/amazon.svg",
                "sort": 1
            }
        ],
        "total": 1
    }
}

Lists platforms with at least one game currently accepted for sale. Each item includes id, name_ru, name_en, icon, receipt_required and sort.

GEThttps://api.cytrongift.com/v1/catalog/platforms

Request

curl https://api.cytrongift.com/v1/catalog/platforms

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": 1,
                "name_ru": "Steam",
                "name_en": "Steam",
                "icon": "",
                "receipt_required": false,
                "sort": 1
            }
        ],
        "total": 1
    }
}

Returns payout methods and the exchange rates used to calculate payouts. Each item includes id, code, currency, network, name_ru, name_en, icon, example, rate, rate_date, round, needs_fio and sort.

GEThttps://api.cytrongift.com/v1/catalog/payments

Request

curl https://api.cytrongift.com/v1/catalog/payments

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": 2,
                "code": "BTC",
                "currency": "BTC",
                "network": "",
                "name_ru": "Bitcoin",
                "name_en": "Bitcoin",
                "icon": "",
                "example": "1A1zP1...",
                "rate": 79728.1,
                "rate_date": 1788605000,
                "round": 8,
                "needs_fio": false,
                "sort": 1
            }
        ],
        "total": 1
    }
}

Returns a paginated list of gift cards. Each item includes id, name_ru, name_en, icon, price, currency_id, country_id, brand_id and sort. The price is in the currency identified by currency_id.

GEThttps://api.cytrongift.com/v1/catalog/cards

Query

NameTypeAbout
brand_idintegerFilter by brand id.
country_idintegerFilter by country id.
searchstringMatch part of the item name.
cursorintegerReturn items with ids greater than this cursor.
limitinteger, default 50Items per page: 1 to 500.

Request

curl https://api.cytrongift.com/v1/catalog/cards

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": 1,
                "name_ru": "Amazon 100 USD",
                "name_en": "Amazon 100 USD",
                "icon": "",
                "price": 85,
                "currency_id": 1,
                "country_id": 9,
                "brand_id": 1,
                "sort": 0
            }
        ],
        "limit": 50,
        "cursor": 0,
        "next_cursor": null,
        "filters": {
            "brand_id": null,
            "country_id": null,
            "search": ""
        }
    }
}

Returns a paginated list of game keys. Items have the same fields as gift cards, with platform_id instead of brand_id.

GEThttps://api.cytrongift.com/v1/catalog/games

Query

NameTypeAbout
platform_idintegerFilter by platform id.
country_idintegerFilter by country id.
searchstringMatch part of the item name.
cursorintegerReturn items with ids greater than this cursor.
limitinteger, default 50Items per page: 1 to 500.

Request

curl https://api.cytrongift.com/v1/catalog/games

Response

{
    "ok": 1,
    "data": {
        "items": [],
        "limit": 50,
        "cursor": 0,
        "next_cursor": null,
        "filters": []
    }
}

Pass either platform_id or brand_id; omitting both returns 4012. If you send both, platform_id takes priority.

Each item includes country_id, title in the requested language, code (a lowercase ISO 3166-1 alpha-2 code) and flag.

GEThttps://api.cytrongift.com/v1/catalog/countries

Query

NameTypeAbout
brand_idintegerBrand id.
platform_idintegerPlatform id.

Request

curl https://api.cytrongift.com/v1/catalog/countries

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "country_id": 9,
                "title": "USA",
                "code": "us",
                "flag": "/templates/frontend/cytron/images/flags/us.svg"
            }
        ],
        "total": 1,
        "filters": {
            "brand_id": 1
        }
    }
}

Lists the gift cards currently accepted for sale, priced in USD, in the order the website shows them. Each item has id (the card id), category_id (the brand), country_id, name_en, name_ru, amount (a number) and has_image. Page with next_offset; it is null on the last page. An invalid offset, limit or search gives 4012.

GEThttps://api.cytrongift.com/v1/catalog/offers

Query

NameTypeAbout
offsetinteger, default 0Rows to skip, default 0.
limitinteger, default 10Page size from 1 to 100, default 10.
searchstringPart of the English or Russian name, up to 100 characters.

Request

curl https://api.cytrongift.com/v1/catalog/offers

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": 42,
                "category_id": 3,
                "country_id": 10,
                "name_en": "Apple Gift Card US",
                "name_ru": "Apple Gift Card US",
                "amount": 8.08,
                "has_image": true
            }
        ],
        "currency": "USD",
        "symbol": "$",
        "next_offset": 10
    }
}

Streams a public catalogue image (a brand, platform, card or game logo, a country flag or a payment method icon) with its own content type and cache headers. A card or game logo is served as long as the item is not deleted, even after it left the sale; a brand, platform, country or payment icon needs an active row. An unknown or deleted item, or a kind without a logo, gives 4007; a malformed id or kind gives 4012.

GEThttps://api.cytrongift.com/v1/catalog/images

Query

NameTypeAbout
kind *stringWhat the id refers to.
id *integerThe id of the item.

Request

curl https://api.cytrongift.com/v1/catalog/images

Response

{
    "ok": 1,
    "data": []
}

Auth

Create, refresh and revoke tokens for API access.

Sign this request with your application key. An existing token cannot be used to create another one.

The token stays linked to the application that signed the request. ttl is limited to 300 through 86400 seconds; if omitted, the site default applies.

POSThttps://api.cytrongift.com/v1/auth

Body (optional)

{
    "ttl": 3600
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/auth\n%s\n{"ttl":3600}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/auth \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"ttl":3600}'

Response

{
    "ok": 1,
    "data": {
        "token_type": "Bearer",
        "access_token": "eyJ...",
        "expires_in": 3600,
        "expires_at": 1788608789,
        "merchant_id": 8269
    }
}

For first-party applications only: kind first_party, scope identity:assert. Sign the request with the application key.

Before calling this endpoint, verify the provider's credentials on your own server: for example, Telegram initData with the bot token, or a Discord OAuth code. The API looks up the account by provider and provider_uid. If none exists, it creates one from profile (first_name, last_name, username, photo_url, language_code).

A new account gets its inviter from start_param (up to 64 characters, the Telegram launch parameter as the user opened it): ref_<id> names the inviting account by id, bare digits name an account created before the referral codes, any other value is read as a referral code. When start_param names nobody, referral_code is tried. Both apply only to an account this call creates; an existing account keeps its inviter.

The response contains an opaque token pair for the user and the account's mailbox state: user.email (empty for an account born from a provider) and user.email_verified. You can pass a device label of up to 64 characters. ttl is limited to 300 through 86400 seconds for the access token. The token inherits the application's scopes except identity:assert.

If the Telegram id is still linked to a legacy account, you get 4084 with link_required. The user needs to link that account on the website first.

Send create: false to look the identity up without registering anyone: an unknown identity answers 404 with error 4146 and reason: identity_unknown, and nothing is created. This is the first step of the e-mail first sign-in, see POST /auth/identity/claim. client_ip (optional) is the visitor's address as your server saw it; a new account counts against the per-address sign-up limit with it instead of your server's address. An invalid address answers 4082 with field: client_ip.

POSThttps://api.cytrongift.com/v1/auth/identity

Body

{
    "provider": "telegram",
    "provider_uid": "123456789",
    "profile": {
        "first_name": "Ada",
        "last_name": "",
        "username": "ada",
        "photo_url": "",
        "language_code": "ru"
    },
    "start_param": "ref_8607",
    "referral_code": "ada7",
    "create": true,
    "client_ip": "198.51.100.7",
    "device": "Mini App iPhone",
    "ttl": 3600
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/auth/identity\n%s\n{"provider":"telegram","provider_uid":"123456789","profile":{"first_name":"Ada","last_name":"","username":"ada","photo_url":"","language_code":"ru"},"start_param":"ref_8607","referral_code":"ada7","create":true,"client_ip":"198.51.100.7","device":"Mini App iPhone","ttl":3600}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/auth/identity \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"provider":"telegram","provider_uid":"123456789","profile":{"first_name":"Ada","last_name":"","username":"ada","photo_url":"","language_code":"ru"},"start_param":"ref_8607","referral_code":"ada7","create":true,"client_ip":"198.51.100.7","device":"Mini App iPhone","ttl":3600}'

Response

{
    "ok": 1,
    "data": {
        "token_type": "Bearer",
        "access_token": "ut_...",
        "expires_in": 3600,
        "expires_at": 1788608789,
        "refresh_token": "rt_...",
        "refresh_expires_at": 1791197189,
        "scopes": [
            "catalog:read",
            "account:read",
            "orders:read",
            "orders:write"
        ],
        "user": {
            "id": 9001,
            "login": "ada",
            "ref_code": "ada7",
            "email": "",
            "email_verified": false,
            "created": true
        }
    }
}

For first-party applications only: kind first_party, scope identity:assert. Sign the request with the application key.

The e-mail first sign-in of a member whose identity has no account yet (POST /auth/identity with create: false answered 4146), or whose account has no confirmed address. Verify the provider's credentials on your server first, exactly as for POST /auth/identity.

The API mails a six-digit code to email and keeps only its hash. The code works for 15 minutes, once, and only for the same provider and provider_uid; a new claim replaces the previous one. When you pass confirm_link, a Telegram Mini App link ending in ?startapp= (https://t.me/<bot>/<app>?startapp= or https://t.me/<bot>?startapp=), the mail also carries an Open in Telegram button: the link with c_<token> appended, which reopens your app. Read the token from the launch parameter and confirm with it.

The answer, the mail and the work done are the same whether or not an account with this address exists, is blocked or already holds another Telegram, so the call cannot be used to find out who is registered. retry_after is the number of seconds before this identity may ask for another mail; expires_in is the life of the code.

Send client_ip, the visitor's address as your server saw it: the limits count it. Limits: one mail a minute and five an hour per identity, three an hour per address, ten claims an hour per visitor address; a hit answers 429 with error 4088, reason: claim_wait, retry_after and a Retry-After header. After ten wrong codes within a day the identity is locked: 429, error 4147, reason: claim_locked. A malformed address answers 4059 with reason: email_invalid, a throwaway mail domain 4059 with reason: email_blocked.

POSThttps://api.cytrongift.com/v1/auth/identity/claim

Body

{
    "provider": "telegram",
    "provider_uid": "123456789",
    "profile": {
        "first_name": "Ada",
        "last_name": "",
        "username": "ada",
        "photo_url": "",
        "language_code": "ru"
    },
    "email": "[email protected]",
    "lang": "ru",
    "start_param": "ref_8607",
    "device": "Mini App iPhone",
    "client_ip": "198.51.100.7",
    "confirm_link": "https://t.me/cytrongift_bot/app?startapp="
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/auth/identity/claim\n%s\n{"provider":"telegram","provider_uid":"123456789","profile":{"first_name":"Ada","last_name":"","username":"ada","photo_url":"","language_code":"ru"},"email":"[email protected]","lang":"ru","start_param":"ref_8607","device":"Mini App iPhone","client_ip":"198.51.100.7","confirm_link":"https://t.me/cytrongift_bot/app?startapp="}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/auth/identity/claim \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"provider":"telegram","provider_uid":"123456789","profile":{"first_name":"Ada","last_name":"","username":"ada","photo_url":"","language_code":"ru"},"email":"[email protected]","lang":"ru","start_param":"ref_8607","device":"Mini App iPhone","client_ip":"198.51.100.7","confirm_link":"https://t.me/cytrongift_bot/app?startapp="}'

Response

{
    "ok": 1,
    "data": {
        "sent": true,
        "retry_after": 60,
        "expires_in": 900
    }
}

For first-party applications only: kind first_party, scope identity:assert. Sign the request with the application key.

Send the same provider and provider_uid that asked for the code and exactly one proof: code, the six digits as a string, or token, the 32 characters after c_ in the launch parameter the mail button opened your app with. A proof only opens the claim of the identity that made it: the code of another identity never matches.

The answer is the body of POST /auth/identity (a token pair and user) plus outcome and email, the confirmed address:

- created: no account had this address; a new one exists now with the address confirmed and the identity attached, and the inviter from the claim's start_param is applied. - linked: an account with this address existed; the identity is attached to it and the owner gets a notice mail. If the identity belonged to an account born in your app, that account is archived when empty or merged when the account link would merge it by itself; otherwise 4142 and an operator decides. An account of another identity that only wrote the address without confirming it loses the address and does not count. If the account had never confirmed the address, its password, website sessions and tokens are cleared first, so whoever registered the address without owning the mailbox loses access. - updated: the identity's own account had no confirmed address and nobody else holds this one; the address is set on it, confirmed.

Two-factor authentication. When the account that will hold the identity (linked, or the identity's own account on updated) has two-factor authentication on, the proven code or token is not enough: the call answers 403 4150 totp_required. Nothing is attached, the claim stays live and no attempt is counted, so ask the member for the six digits of their authenticator app and send the same code again together with totp (six digits as a string). After a refused token send the mailed code with totp; the token works as well while the claim lives. A wrong totp answers 400 4151 totp_invalid and counts as one wrong proof of the claim and of the day. While the account's second factor is locked after wrong codes the confirm answers 429 4156 totp_locked with retry_after; the claim keeps its attempts and the same proof works once the lock has passed, if the code still lives. created never asks, and an account that never confirmed its address is not asked either: its password and its authenticator are cleared with it. A staff account stays closed (4102) unless the installation lists the Telegram id and the account has two-factor on, so this step always runs for it.

Refusals carry reason: a wrong proof 400 4148 code_invalid (nothing about the attempts left; five wrong proofs end the claim); no live claim (expired, used, ended by wrong proofs, replaced or never made) 410 4149 claim_expired; ten wrong proofs within a day 429 4147 claim_locked with retry_after; the account that confirmed the address already holds another identity of this provider, or the identity is on an account with another confirmed address, 409 4140 claim_conflict; the account may not sign in (blocked, deleted, a staff account) 403 4102 claim_refused; the Telegram id sits on a legacy account 409 4084 link_required; a merge that needs an operator 409 4142 link_manual_review; another sign-in of the same identity is running 503 4145 identity_busy; too many new accounts from the visitor's address 429 3011 registration_throttled. A conflict, a refusal, link_required and a review spend the claim; after 3011 or 4145 the same proof may be sent again while the code lives.

POSThttps://api.cytrongift.com/v1/auth/identity/claim/confirm

Body

{
    "provider": "telegram",
    "provider_uid": "123456789",
    "code": "042137",
    "totp": "918273",
    "device": "Mini App iPhone",
    "client_ip": "198.51.100.7"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/auth/identity/claim/confirm\n%s\n{"provider":"telegram","provider_uid":"123456789","code":"042137","totp":"918273","device":"Mini App iPhone","client_ip":"198.51.100.7"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/auth/identity/claim/confirm \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"provider":"telegram","provider_uid":"123456789","code":"042137","totp":"918273","device":"Mini App iPhone","client_ip":"198.51.100.7"}'

Response

{
    "ok": 1,
    "data": {
        "token_type": "Bearer",
        "access_token": "ut_...",
        "expires_in": 3600,
        "expires_at": 1788608789,
        "refresh_token": "rt_...",
        "refresh_expires_at": 1791197189,
        "scopes": [
            "catalog:read",
            "account:read",
            "orders:read",
            "orders:write"
        ],
        "user": {
            "id": 9001,
            "login": "ada",
            "ref_code": "ada7",
            "email": "[email protected]",
            "email_verified": true,
            "created": false
        },
        "outcome": "linked",
        "email": "[email protected]"
    }
}

Exchanges a refresh token for a new token pair. Each refresh token works once; the old pair becomes invalid as soon as the new one is issued. A reused or revoked refresh token returns 3009; an expired one returns 3008.

POSThttps://api.cytrongift.com/v1/auth/refresh

Body

{
    "refresh_token": "rt_...",
    "ttl": 3600
}

Request

curl https://api.cytrongift.com/v1/auth/refresh

Response

{
    "ok": 1,
    "data": {
        "token_type": "Bearer",
        "access_token": "ut_...",
        "expires_in": 3600,
        "expires_at": 1788608789,
        "refresh_token": "rt_...",
        "refresh_expires_at": 1791197189,
        "scopes": [
            "catalog:read",
            "account:read",
            "orders:read",
            "orders:write"
        ]
    }
}

Immediately revokes the opaque user token used for this request. JWTs cannot be revoked through this endpoint and return 4082.

POSThttps://api.cytrongift.com/v1/auth/logout

Body

[]

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/auth/logout\n%s\n[]' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/auth/logout \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '[]'

Response

{
    "ok": 1,
    "data": {
        "revoked": true
    }
}

For first-party applications: scope identity:link, called with the user's token (or the application key for its own account). Opens a challenge for the Telegram identity the acting user holds. The body is {} or {"purpose": "link"} for a link, {"purpose": "assessment"} for a report only.

Keep id and secret on your server: they are the proof for status, cancel, assessment and complete. Show website_url to the user; the site page asks the signed-in owner of the site account to approve. The challenge lives expires_in seconds (600); a new start cancels the open one.

An account that is already a site account, or a Telegram id already linked, returns 4140 with already_linked. A user without a Telegram identity gets 4144.

POSThttps://api.cytrongift.com/v1/identities/link/start

Body (optional)

{
    "purpose": "link"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/identities/link/start\n%s\n{"purpose":"link"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/identities/link/start \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"purpose":"link"}'

Response

{
    "ok": 1,
    "data": {
        "purpose": "link",
        "id": "4cfd03147dc461f0a41324ac5cce8fef",
        "secret": "9f2c...64 hex characters",
        "website_url": "https://cytrongift.com/en/account/link/#4cfd03147dc461f0a41324ac5cce8fef.5be1...",
        "expires_in": 600,
        "provider": "telegram",
        "provider_uid": "123456789"
    }
}

No credentials: the proof id and secret from /identities/link/start is the authorisation. status is pending until the site owner approves, then approved with the site account; completed after /identities/link/complete; review when the link waits for an operator (see 4142). A wrong, cancelled or expired proof returns 4143.

POSThttps://api.cytrongift.com/v1/identities/link/status

Body

{
    "id": "4cfd03147dc461f0a41324ac5cce8fef",
    "secret": "9f2c...64 hex characters"
}

Request

curl https://api.cytrongift.com/v1/identities/link/status

Response

{
    "ok": 1,
    "data": {
        "purpose": "link",
        "status": "approved",
        "account": {
            "id": "8269",
            "display_name": "Ada Lovelace"
        }
    }
}

No credentials: the proof id and secret is the authorisation. Closes an open challenge; cancelled is false for one already completed. A wrong, cancelled or expired proof returns 4143.

POSThttps://api.cytrongift.com/v1/identities/link/cancel

Body

{
    "id": "4cfd03147dc461f0a41324ac5cce8fef",
    "secret": "9f2c...64 hex characters"
}

Request

curl https://api.cytrongift.com/v1/identities/link/cancel

Response

{
    "ok": 1,
    "data": {
        "cancelled": true
    }
}

No credentials: the proof id and secret of an approved challenge, of either purpose. Reports what stands between the Telegram account (source) and the site account (target): balances, history counts, outcome (no_obstacles, manual_review or blocked) and reasons. Nothing changes; execution_available is always false.

complete_available says whether /identities/link/complete would go through by itself: the source is empty, or the outcome is no_obstacles and balance_moved (both source balances, USD) is at most auto_merge_max (100). Otherwise completion returns 4142. A challenge not approved yet returns 4140 with link_not_approved.

POSThttps://api.cytrongift.com/v1/identities/link/assessment

Body

{
    "id": "4cfd03147dc461f0a41324ac5cce8fef",
    "secret": "9f2c...64 hex characters"
}

Request

curl https://api.cytrongift.com/v1/identities/link/assessment

Response

{
    "ok": 1,
    "data": {
        "checked_at": 1793965869,
        "execution_available": false,
        "outcome": "no_obstacles",
        "source": {
            "id": "9001",
            "display_name": "Ada",
            "balances": {
                "main": 20,
                "referral": 0
            },
            "counts": {
                "orders": 0,
                "active_orders": 0,
                "withdrawals": 0,
                "active_withdrawals": 0,
                "referral_credits": 0,
                "invited": 0,
                "referred_orders": 0,
                "tickets": 0,
                "reviews": 0,
                "sale_receipts": 0,
                "withdrawal_receipts": 0
            }
        },
        "target": {
            "id": "8269",
            "display_name": "Ada Lovelace",
            "balances": {
                "main": 5,
                "referral": 0
            },
            "counts": {
                "orders": 0,
                "active_orders": 0,
                "withdrawals": 0,
                "active_withdrawals": 0,
                "referral_credits": 0,
                "invited": 0,
                "referred_orders": 0,
                "tickets": 0,
                "reviews": 0,
                "sale_receipts": 0,
                "withdrawal_receipts": 0
            }
        },
        "combined_balances": {
            "main": 25,
            "referral": 0
        },
        "reasons": [],
        "complete_available": true,
        "balance_moved": 20,
        "auto_merge_max": 100
    }
}

Complete a link and get tokens for the site account

For first-party applications only: scope identity:link, signed with the application key. The body is the proof id and secret of an approved link challenge, with an optional device label and ttl as in /auth/identity.

The Telegram identity moves onto the site account. A Telegram account with nothing on it is archived. One with history or money is merged into the site account (balances, orders, withdrawals, referrals, tickets) only when the assessment found no obstacles and at most 100 USD moves; otherwise the call returns 4142 with the outcome, reasons and balance_moved in extra, nothing changes, and the challenge stays for an operator with status review.

The answer has the shape of /auth/identity for the site account, with user.created false; the tokens of the Telegram account stop working. Repeating the call after a lost answer issues a fresh pair without moving anything again. A challenge not approved, or a site session that ended before completion, returns 4140.

POSThttps://api.cytrongift.com/v1/identities/link/complete

Body

{
    "id": "4cfd03147dc461f0a41324ac5cce8fef",
    "secret": "9f2c...64 hex characters",
    "device": "Mini App iPhone",
    "ttl": 3600
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/identities/link/complete\n%s\n{"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"9f2c...64 hex characters","device":"Mini App iPhone","ttl":3600}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/identities/link/complete \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"9f2c...64 hex characters","device":"Mini App iPhone","ttl":3600}'

Response

{
    "ok": 1,
    "data": {
        "token_type": "Bearer",
        "access_token": "ut_...",
        "expires_in": 3600,
        "expires_at": 1793969468,
        "refresh_token": "rt_...",
        "refresh_expires_at": 1796557868,
        "scopes": [
            "catalog:read",
            "account:read",
            "orders:read",
            "orders:write",
            "profile:write",
            "support:write",
            "identity:link",
            "notifications:manage"
        ],
        "user": {
            "id": 8269,
            "login": "ada",
            "ref_code": "ada7",
            "email": "[email protected]",
            "email_verified": true,
            "created": false
        }
    }
}

Called by the site page /<lang>/account/link/ on the site address, not by applications: it carries the site session cookie and the X-CSRF-Token header. The body is the website half of the proof from the hash of website_url and approve: false only reads the pair, true approves it for the signed-in account.

Without a signed-in site session the call returns 4140 with website_session_required; a challenge another account has taken returns 4140 with link_conflict; an expired one 4143.

POSThttps://api.cytrongift.com/v1/identities/link/website

Body

{
    "id": "4cfd03147dc461f0a41324ac5cce8fef",
    "secret": "5be1...64 hex characters",
    "approve": true
}

Request

curl https://api.cytrongift.com/v1/identities/link/website

Response

{
    "ok": 1,
    "data": {
        "purpose": "link",
        "status": "approved",
        "account": {
            "id": "8269",
            "display_name": "Ada Lovelace"
        },
        "telegram": {
            "id": "123456789",
            "display_name": "Ada"
        }
    }
}

Account

Read your balance, orders and bonus level, update your profile, manage webhooks.

Returns your current account balance, read directly from the account record.

GEThttps://api.cytrongift.com/v1/account/balance

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/balance\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/balance \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "balance": 250,
        "referrals_earned": 0,
        "referrals_count": 0,
        "currency_code": "USD",
        "currency_symbol": "$"
    }
}

Returns your bonus level based on completed payouts. next_level is null if you have reached the highest tier.

GEThttps://api.cytrongift.com/v1/account/bonus

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/bonus\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/bonus \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "user": {
            "id": 8269,
            "login": "seller",
            "fullname": "",
            "email": "[email protected]"
        },
        "current": {
            "level": 0,
            "bonus_percent": 0,
            "unlock_amount": 10000,
            "progress_to_next": 0,
            "next_level": 1
        },
        "levels": [
            {
                "level": 1,
                "threshold": 10000,
                "bonus_percent": 0.05
            }
        ]
    }
}

Returns order totals grouped by status. processing includes statuses 0 and 3.

GEThttps://api.cytrongift.com/v1/account/analytics

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/analytics\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/analytics \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "complete": {
            "amount": 0,
            "quantity": 0,
            "orders": 0
        },
        "processing": {
            "amount": 0,
            "quantity": 0,
            "orders": 0
        },
        "rejected": {
            "amount": 0,
            "quantity": 0,
            "orders": 0
        }
    }
}

Returns your orders, newest first. Pass id to fetch a single order directly in data, without the list wrapper. If the order does not belong to your account, you get 4007.

Each item includes id, uuid, type, status (processing|complete|rejected|under_review), status_id, gift_id, brand_id, country_id, item, amount, total, net_total, quantity, cards_type, cards_list, user_images, receipt_images, user_comment, admin_comment, date_create, date_created and date_complete.

Each image entry includes a url pointing to GET /account/order-image.

GEThttps://api.cytrongift.com/v1/account/transactions

Query

NameTypeAbout
idintegerReturn one order directly in data, without the list wrapper.
typestringcards or games
cursorintegerReturn items with ids less than this cursor.
limitinteger, default 20Items per page: 1 to 200.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/transactions\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/transactions \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "items": [],
        "limit": 20,
        "cursor": 0,
        "next_cursor": null,
        "filters": {
            "type": null
        }
    }
}

Streams an order image as image/webp with Cache-Control: private, no-store. Use the token from the image's url; no other image identifier is needed. If it does not identify an image in your account, you get 4007.

GEThttps://api.cytrongift.com/v1/account/order-image

Query

NameTypeAbout
token *stringThe token from the image URL.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/order-image\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/order-image \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": []
}

Returns your profile fields.

GEThttps://api.cytrongift.com/v1/account/settings

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/settings\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/settings \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "id": 8269,
        "login": "seller",
        "email": "[email protected]",
        "email_verified": false,
        "firstname": "",
        "lastname": "",
        "fullname": "",
        "country": "USA",
        "country_id": 9,
        "city": "Berlin",
        "telegram": "seller",
        "whatsapp": "",
        "phone": "",
        "userpic": ""
    }
}

Send only the fields you want to change: phone, whatsapp, fullname, city, telegram or country_id. An empty object returns 4012.

Phone fields accept 10 to 13 digits or an empty value. Names accept letters, spaces, apostrophes and hyphens, with a length of 2 to 128 characters. A leading @ is removed from telegram; the remaining value must match [a-zA-Z0-9_]{3,32}. Use a country_id from /catalog/country2data.

PATCHhttps://api.cytrongift.com/v1/account/settings

Body

{
    "city": "Berlin",
    "telegram": "@seller"
}

Request

TS=$(date +%s)
SIG=$(printf 'PATCH\n/account/settings\n%s\n{"city":"Berlin","telegram":"@seller"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X PATCH https://api.cytrongift.com/v1/account/settings \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"city":"Berlin","telegram":"@seller"}'

Response

{
    "ok": 1,
    "data": {
        "updated": true,
        "settings": {
            "id": 8269,
            "city": "Berlin"
        }
    }
}

Lists the delivery addresses of your account with the events they receive. The secret is never shown again; register the address again to get a new one.

GEThttps://api.cytrongift.com/v1/account/webhooks

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/webhooks\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/webhooks \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": 12,
                "url": "https://partner.example.com/cytrongift/hook",
                "enabled": true,
                "events": [
                    "order.completed",
                    "order.rejected",
                    "withdrawal.completed",
                    "withdrawal.rejected",
                    "application.approved",
                    "application.rejected",
                    "application.paused"
                ],
                "created_at": 1788605154
            }
        ],
        "limit": 5
    }
}

Registers an https address for the events listed under Webhooks in the guide. The answer carries the secret once; registering an address you already hold issues a new secret for it. An address held by another account returns 4008, an invalid one 4082, the sixth address 4085.

POSThttps://api.cytrongift.com/v1/account/webhooks

Body

{
    "url": "https://partner.example.com/cytrongift/hook"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/webhooks\n%s\n{"url":"https://partner.example.com/cytrongift/hook"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/webhooks \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"url":"https://partner.example.com/cytrongift/hook"}'

Response

{
    "ok": 1,
    "data": {
        "id": 12,
        "url": "https://partner.example.com/cytrongift/hook",
        "enabled": true,
        "events": [
            "order.completed",
            "order.rejected",
            "withdrawal.completed",
            "withdrawal.rejected",
            "application.approved",
            "application.rejected",
            "application.paused"
        ],
        "created_at": 1788605154,
        "secret": "7f3a...c9e1"
    }
}

Drops one address of your account; deliveries still waiting for it are cancelled. An unknown id, or one held by another account, returns 4007.

POSThttps://api.cytrongift.com/v1/account/webhooks/delete

Body

{
    "id": 12
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/webhooks/delete\n%s\n{"id":12}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/webhooks/delete \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"id":12}'

Response

{
    "ok": 1,
    "data": {
        "id": 12,
        "deleted": true
    }
}

Returns who the acting user is, for an application's own screens. display_name is the full name, or the login when none is set; username is the Telegram handle; avatar_url is the uploaded picture, else the provider's photo, else null. has_password tells whether the account can sign in on the website with a password, site_account whether it has a mailbox or a password at all. two_factor tells whether two-factor authentication is on: sign-in by e-mail code and payouts made with a user token then ask for a code of the authenticator app. An account with has_password false gets its first website password through POST /account/password/setup. email_verified must be true before POST /sell/cards, POST /sell/games and POST /withdrawal/create accept the account; add an address with POST /account/email. level is the bonus level: level, bonus (percent), unlock (amount left to the next level) and progress_to_next (percent). registered is a unix time.

GEThttps://api.cytrongift.com/v1/account/profile

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/profile\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/profile \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "id": 9001,
        "login": "ada",
        "display_name": "Ada Lovelace",
        "username": "ada",
        "avatar_url": "https://cytrongift.com/uploads/userpic/9001.webp",
        "email": "[email protected]",
        "email_verified": true,
        "has_password": false,
        "two_factor": false,
        "site_account": true,
        "ref_code": "ada7",
        "lang": "en",
        "level": {
            "level": 2,
            "bonus": 1.5,
            "unlock": 120.5,
            "progress_to_next": 60
        },
        "registered": 1788600000
    }
}

Stores a mailbox for an account whose address is not yet confirmed and mails it the verification link at once; the link opens the website's verification page. A confirmed account answers 4082 with already_verified. An invalid address or a throwaway domain answers 4059; an address another account holds answers 4087. Verification mails are limited to one a minute and five an hour per account: a request too soon answers 4088 with retry_after in seconds. retry_after in the answer says when the next mail may be asked for.

POSThttps://api.cytrongift.com/v1/account/email

Body

{
    "email": "[email protected]"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/email\n%s\n{"email":"[email protected]"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/email \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"email":"[email protected]"}'

Response

{
    "ok": 1,
    "data": {
        "email": "[email protected]",
        "email_verified": false,
        "sent": true,
        "retry_after": 60
    }
}

Mails the verification link to the stored address again. Each mail carries a new link; the link of an earlier mail stops working. An account without an address answers 4082 with email_missing, a confirmed one 4082 with already_verified. Verification mails are limited to one a minute and five an hour per account: a request too soon answers 4088 with retry_after in seconds.

POSThttps://api.cytrongift.com/v1/account/email/resend

Body (optional)

[]

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/email/resend\n%s\n[]' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/email/resend \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '[]'

Response

{
    "ok": 1,
    "data": {
        "email": "[email protected]",
        "email_verified": false,
        "sent": true,
        "retry_after": 60
    }
}

Only for a user token (Bearer ut_...): the proof belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

Mails a fresh six-digit code to the confirmed address of the account, in the user's language, for an action your application guards on its own side. purpose is required and names that action; pin_reset (removing the app PIN of the Mini App) is the only one for now, anything else answers 400 with error 4082. The code works for 15 minutes (expires_in, seconds) and a new mail voids the earlier code. The answer shows the address masked (d***@mail.com) and retry_after, the seconds before the next mail may be asked. One mail a minute and three an hour per account: a request too soon answers 429 with error 4158, retry_after and a Retry-After header. An account without a confirmed address answers 403 with 4086. Check the code with POST /account/email/code/confirm.

POSThttps://api.cytrongift.com/v1/account/email/code

Body

{
    "purpose": "pin_reset"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/email/code\n%s\n{"purpose":"pin_reset"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/email/code \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"purpose":"pin_reset"}'

Response

{
    "ok": 1,
    "data": {
        "sent": true,
        "email": "d***@mail.com",
        "expires_in": 900,
        "retry_after": 60
    }
}

Only for a user token (Bearer ut_...): the proof belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

Checks the code of the latest POST /account/email/code mail for the same purpose. Send code as a string of six digits. A right code is spent at once and answers verified: true. A wrong one answers 400 with error 4159 and attempts_left; the fifth wrong try voids the code. No live code for the purpose (never sent, expired, used, replaced by a newer mail or out of tries) answers 409 with error 4160: ask for a new mail. Never retry a wrong code automatically.

POSThttps://api.cytrongift.com/v1/account/email/code/confirm

Body

{
    "purpose": "pin_reset",
    "code": "402518"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/email/code/confirm\n%s\n{"purpose":"pin_reset","code":"402518"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/email/code/confirm \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"purpose":"pin_reset","code":"402518"}'

Response

{
    "ok": 1,
    "data": {
        "verified": true
    }
}

Tells whether two-factor authentication is on for the acting account. It is the same switch as on the Security page of the website: enabling it in one place shows in the other, and one key serves both.

GEThttps://api.cytrongift.com/v1/account/2fa

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/2fa\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/2fa \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "enabled": false
    }
}

Only for a user token (Bearer ut_...): the second factor belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

Returns a new key for an authenticator app: secret (base32, for typing by hand), uri (the otpauth:// address) and qr, the SVG markup of the QR code exactly as the website draws it (an empty string if it could not be drawn; the key still works). Nothing is switched on yet: the key waits with the account until POST /account/2fa/enable brings its first code, and asking again replaces it. An account with two-factor already on answers 409 with error 4152; switch it off first.

POSThttps://api.cytrongift.com/v1/account/2fa/setup

Body (optional)

[]

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/2fa/setup\n%s\n[]' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/2fa/setup \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '[]'

Response

{
    "ok": 1,
    "data": {
        "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
        "uri": "otpauth://totp/Cytrongift:ada?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Cytrongift&algorithm=SHA1&digits=6&period=30",
        "qr": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"210\" height=\"210\" viewBox=\"0 0 53 53\">...</svg>"
    }
}

Only for a user token (Bearer ut_...): the second factor belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

Send code, the six digits the authenticator app shows for the key of POST /account/2fa/setup, as a string. A wrong code answers 400 with error 4151; without a waiting setup the answer is 409 with 4153, with two-factor already on 409 with 4152. From this moment the website sign-in, the sign-in by e-mail code and payouts made with a user token ask for a code. The code that enabled it is used up: the next action needs the next code. Five wrong codes within 15 minutes lock the second factor of the account: 429 with error 4156 and retry_after.

POSThttps://api.cytrongift.com/v1/account/2fa/enable

Body

{
    "code": "918273"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/2fa/enable\n%s\n{"code":"918273"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/2fa/enable \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"code":"918273"}'

Response

{
    "ok": 1,
    "data": {
        "enabled": true
    }
}

Only for a user token (Bearer ut_...): the second factor belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

Send code, a live code of the authenticator app, as a string: a stolen session alone cannot remove the protection. A wrong or already used code answers 400 with error 4151. The key is deleted; a later setup starts with a new one. Five wrong codes within 15 minutes lock the second factor of the account: 429 with error 4156 and retry_after.

POSThttps://api.cytrongift.com/v1/account/2fa/disable

Body

{
    "code": "918273"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/2fa/disable\n%s\n{"code":"918273"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/2fa/disable \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"code":"918273"}'

Response

{
    "ok": 1,
    "data": {
        "enabled": false
    }
}

Only for a user token (Bearer ut_...): the proof belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

Checks a live code of the authenticator app and changes nothing on the account, for an action your application guards on its own side (removing the app PIN of the Mini App, for example). Send code as a string of six digits. A right code is spent like anywhere else: it works once, so the next check needs the next code. A wrong or already used code answers 400 with error 4151 and counts against the account's lock: five wrong codes within 15 minutes, wherever they were sent, answer 429 with error 4156, retry_after and a Retry-After header, even for a right code. An account with two-factor authentication off answers 409 with error 4157; use POST /account/email/code instead.

POSThttps://api.cytrongift.com/v1/account/2fa/verify

Body

{
    "code": "918273"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/2fa/verify\n%s\n{"code":"918273"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/2fa/verify \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"code":"918273"}'

Response

{
    "ok": 1,
    "data": {
        "verified": true
    }
}

Only for a user token (Bearer ut_...): the second factor belongs to the person, so a request signed with an application key answers 403 3014 with reason: "user_token_required".

An account created in an application has no password (has_password false in GET /account/profile). This mails the website's own password link to the confirmed address of the account, in the user's language; the link works once, for an hour, and a new mail voids the earlier link. An account that already has a password answers 409 with error 4154: it changes the password through the recovery form of the website. An account without a confirmed address answers 403 with 4086. One mail a minute and three an hour per account: a request too soon answers 429 with 4155 and retry_after in seconds. You may send client_ip, the visitor's address, which the site stores with the link.

POSThttps://api.cytrongift.com/v1/account/password/setup

Body (optional)

[]

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/password/setup\n%s\n[]' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/password/setup \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '[]'

Response

{
    "ok": 1,
    "data": {
        "sent": true
    }
}

Your orders and payouts in one feed, newest first, 20 per page. type is all (default), cards, games or withdrawals. Pass the next_cursor of a page as cursor to read the next one; null means there is no more. A cursor of another type or a malformed one returns 4082.

An order row has kind cards or games, the item and its brand or platform and region in both languages, quantity, unit_price, amount and status (processing|complete|rejected|under_review); a payout row has kind: "withdrawals", balance_source, amount and status. Codes, comments and files come from GET /account/history/item.

GEThttps://api.cytrongift.com/v1/account/history

Query

NameTypeAbout
typestring, default allall, cards, games or withdrawals
cursorstringThe next_cursor of the previous page.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/history\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/history \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": "82483",
                "kind": "cards",
                "item_id": 2,
                "name_en": "Apple iTunes 10 USD",
                "name_ru": "Apple iTunes 10 USD",
                "platform_en": "Apple",
                "platform_ru": "Apple",
                "country_en": "USA",
                "country_ru": "США",
                "quantity": 1,
                "unit_price": 7.7,
                "amount": 7.7,
                "status": "processing",
                "created_at": "2026-11-06T11:49:46Z",
                "currency": "USD",
                "symbol": "$"
            },
            {
                "id": "18525",
                "kind": "withdrawals",
                "balance_source": "main",
                "amount": 25,
                "status": "processing",
                "created_at": "2026-11-06T11:50:09Z",
                "currency": "USD",
                "symbol": "$"
            }
        ],
        "next_cursor": "v1.1793965746.0.82483",
        "currency": "USD",
        "symbol": "$"
    }
}

One row of GET /account/history in full. For kind cards or games it adds the submitted codes, your comment, the operator's admin_comment (the reason of a rejection) and the files of the order, each with a url to GET /account/order-image. For kind: "withdrawals" it adds amount_converted, the method, wallet, fio, the txid of a completed payout and the decline_reason of a rejected one; balance_source (main or referral) narrows the lookup to payouts from that balance.

A record that is not yours returns 4007.

GEThttps://api.cytrongift.com/v1/account/history/item

Query

NameTypeAbout
kind *stringcards, games or withdrawals
id *stringThe id of the history row.
balance_sourcestringmain or referral, payouts only.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/history/item\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/history/item \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "id": "82483",
        "kind": "cards",
        "item_id": 2,
        "name_en": "Apple iTunes 10 USD",
        "name_ru": "Apple iTunes 10 USD",
        "platform_en": "Apple",
        "platform_ru": "Apple",
        "country_en": "USA",
        "country_ru": "США",
        "quantity": 1,
        "unit_price": 7.7,
        "amount": 7.7,
        "status": "processing",
        "created_at": "2026-11-06T11:49:46Z",
        "currency": "USD",
        "symbol": "$",
        "codes": [],
        "comment": "",
        "admin_comment": "",
        "files": [
            {
                "id": "54e18c2e55ce6227",
                "kind": "user",
                "name": "82483-user-0-7e182ff4.webp",
                "size": 72,
                "available": true,
                "url": "https://api.cytrongift.com/v1/account/order-image?token=54e18c2e55ce6227"
            }
        ]
    }
}

Lifetime earnings of your account in USD: sales_earned from completed orders, referral_earned from referral credits, and cashflow, their sum. Payouts do not reduce these figures.

GEThttps://api.cytrongift.com/v1/account/summary

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/summary\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/summary \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "sales_earned": 412.5,
        "referral_earned": 12.4,
        "cashflow": 424.9,
        "currency": "USD",
        "symbol": "$"
    }
}

Your referral balance (balance, what you can withdraw with balance_source: "referral"), the members you invited (invited), the orders that paid you a credit (orders), the lifetime credits (earned) and your percent (rate).

code is your invite code; site_link opens the site with it, and telegram_link opens the Mini App with it as the start parameter, or is null while the Mini App is not configured.

GEThttps://api.cytrongift.com/v1/account/referrals

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/referrals\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/referrals \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "balance": 1.5,
        "invited": 3,
        "orders": 5,
        "earned": 12.4,
        "rate": 5,
        "currency": "USD",
        "symbol": "$",
        "code": "cipartnerf20",
        "site_link": "https://cytrongift.com/?r=cipartnerf20",
        "telegram_link": "https://t.me/CytronGiftBot/app?startapp=cipartnerf20"
    }
}

Referral credits and the payouts from your referral balance in one feed, newest first, 20 per page. type is all (default), referrals or withdrawals; pass next_cursor as cursor for the next page. A credit row names the invited member (user_login) and the amount.

GEThttps://api.cytrongift.com/v1/account/referrals/history

Query

NameTypeAbout
typestring, default allall, referrals or withdrawals
cursorstringThe next_cursor of the previous page.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/referrals/history\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/referrals/history \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "id": "18526",
                "kind": "withdrawals",
                "balance_source": "referral",
                "amount": 1.5,
                "status": "processing",
                "created_at": "2026-11-06T11:50:20Z",
                "currency": "USD",
                "symbol": "$"
            },
            {
                "id": "311",
                "kind": "referrals",
                "user_login": "alex",
                "amount": 0.38,
                "status": "complete",
                "created_at": "2026-11-04T09:12:40Z",
                "currency": "USD",
                "symbol": "$"
            }
        ],
        "next_cursor": null,
        "currency": "USD",
        "symbol": "$"
    }
}

For first-party applications: scope notifications:manage. Reads the Telegram notification switch of the acting user, keyed by the Telegram id of the user's identity. enabled is false until the user turns it on; revision counts the writes and is 0 for a switch that was never written.

A user without a Telegram identity gets 4144.

GEThttps://api.cytrongift.com/v1/account/notifications

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/account/notifications\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/account/notifications \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "enabled": false,
        "revision": 0
    }
}

For first-party applications: scope notifications:manage. The body holds exactly two fields: enabled (boolean) and revision (integer), the revision you last read. Any other field, or a value of another type, returns 4082.

The answer carries the new state with revision one higher. When the switch was written after you read it, the revision no longer matches and the call returns 4141: read it again and repeat. Notifications go out in the language of the Telegram profile. A user without a Telegram identity gets 4144; 4145 means another change of the same Telegram id is running, retry in a few seconds.

PATCHhttps://api.cytrongift.com/v1/account/notifications

Body

{
    "enabled": true,
    "revision": 0
}

Request

TS=$(date +%s)
SIG=$(printf 'PATCH\n/account/notifications\n%s\n{"enabled":true,"revision":0}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X PATCH https://api.cytrongift.com/v1/account/notifications \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"enabled":true,"revision":0}'

Response

{
    "ok": 1,
    "data": {
        "enabled": true,
        "revision": 1
    }
}

For first-party applications: scope notifications:manage, and only with a user token (Bearer ut_...); a request signed with an application key answers 403 3014 with reason: "user_token_required".

Tells the core that something happened to the member's security on your side, so the member hears it in Telegram from the bot. The body holds exactly one field, event; pin_reset (the app PIN of the Mini App was removed by a reset with a confirmation code) is the only one for now, anything else answers 400 with error 4082. Never send the PIN or the code.

The answer says whether a message was queued: false when the member's Telegram notifications are off. The same event within an hour answers 429 with error 4161, retry_after and a Retry-After header; treat it as done. Call it after the reset succeeded and do not let its failure undo the reset.

POSThttps://api.cytrongift.com/v1/account/notifications/event

Body

{
    "event": "pin_reset"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/account/notifications/event\n%s\n{"event":"pin_reset"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/account/notifications/event \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"event":"pin_reset"}'

Response

{
    "ok": 1,
    "data": {
        "queued": true
    }
}

Uploads

Upload card and receipt photos before attaching them to an order.

Upload card or receipt photos as multipart/form-data. For the HMAC signature, use an empty body.

Send type as card or receipt (default: card), plus up to 10 images in files[]. For a single image, you can also use file. JPEG, PNG, GIF and WebP are accepted; the format is checked from the file contents. Each image must fit within the site's upload size limit.

Images are converted to WebP, with the longest side limited to 2048 px. Originals are not kept. Attach the uploaded images to an order within 24 hours; unused uploads are deleted after that.

To make a retried upload safe, send one image with your own upload_id (32 lowercase hex characters). The same id with the same file returns the stored row again without storing a second copy; the same id with another file, another type or from another account returns 409 with error 4065, and an id whose file is already attached to an order returns 4066.

POSThttps://api.cytrongift.com/v1/uploads/images

Body

multipart/form-data with the fields named above.

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/uploads/images\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/uploads/images \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -F type=card -F "files[][email protected]"

Response

{
    "ok": 1,
    "data": {
        "items": [
            {
                "upload_id": "941c...29f",
                "type": "card",
                "mime": "image/webp",
                "size": 13352,
                "w": 2048,
                "h": 1365,
                "created_at": 1788605305,
                "expires_at": 1788691705
            }
        ],
        "total": 1
    }
}

Deletes an upload before it is attached to an order. An attached file returns 4066, an upload owned by another account returns 4008, and an unknown id returns 4007.

POSThttps://api.cytrongift.com/v1/uploads/delete

Body

{
    "upload_id": "941c...29f"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/uploads/delete\n%s\n{"upload_id":"941c...29f"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/uploads/delete \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"upload_id":"941c...29f"}'

Response

{
    "ok": 1,
    "data": {
        "upload_id": "941c...29f",
        "deleted": true
    }
}

Returns what POST /uploads/images accepts: the formats in extensions, the size limit of one image (max_file_bytes) and of one request (max_batch_bytes), the images per request (max_files) and how long an unused upload is kept (expires_in, seconds).

pending lists your uploads that no order has claimed yet and that have not expired, newest first, at most 100, so a client can restore its queue after a restart.

GEThttps://api.cytrongift.com/v1/uploads/config

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/uploads/config\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/uploads/config \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "extensions": [
            "jpg",
            "png",
            "gif",
            "webp",
            "jpeg"
        ],
        "max_file_bytes": 52428800,
        "max_batch_bytes": 52428800,
        "max_files": 10,
        "expires_in": 86400,
        "pending": [
            {
                "upload_id": "0123456789abcdef0123456789abcdef",
                "type": "card",
                "mime": "image/webp",
                "size": 72,
                "w": 8,
                "h": 8,
                "created_at": 1793965776,
                "expires_at": 1794052176
            }
        ]
    }
}

Returns the stored WebP of one of your pending uploads as image/webp with Cache-Control: private, no-store. An upload of another account returns 4008; an unknown, expired or already attached one returns 4007 (attached files are read through GET /account/order-image).

GEThttps://api.cytrongift.com/v1/uploads/preview

Query

NameTypeAbout
upload_id *stringThe upload_id from POST /uploads/images.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/uploads/preview\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/uploads/preview \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

A successful JSON response with an empty data field.

Sell

Create orders to sell gift cards and game keys.

Creates a gift card order with status 0. Set type to 0 for any form, 1 for an e-code, or 2 for a physical card. The gift_id must be available for sale and match brand_id and country_id; a mismatch returns 4063.

Set quantity from 1 to 1000. You can add a comment of up to 1000 characters. In cards, send one code per line, up to 1000 codes with 4 to 92 characters each. Codes are required unless type is 2; physical cards require card_upload_ids instead. Missing card data returns 4064. Uploads must belong to your account, match the required type and be unused by any other order.

In the response, amount is the payout per item, total includes the bonus for the whole order, and net_total is the total before the bonus.

Send request_id (32 to 128 characters of [A-Za-z0-9_-], or the Idempotency-Key header) to make retries safe. A repeat with the same id and the same body returns the stored answer with duplicate: true and creates nothing; the same id with a different body returns 409 with error 4065. When you cannot tell whether a request arrived, ask GET /sell/requests: an id it has never seen is cancelled from then on, and a create with it returns 409 with error 4090. Two requests of one account at the same moment wait for each other; after five seconds the second returns 4091.

Add expected_quote with the unit_price and total from POST /sell/quote to sell only at that price: if the price moved, nothing is created and the answer is 200 with status: "price_changed" and the fresh quote. The acting account needs a confirmed e-mail address; otherwise the call answers 403 with error 4086.

POSThttps://api.cytrongift.com/v1/sell/cards

Body

{
    "type": 1,
    "country_id": 9,
    "brand_id": 1,
    "gift_id": 1,
    "quantity": 2,
    "comment": "",
    "cards": "CODE-1\\nCODE-2",
    "card_upload_ids": [],
    "receipt_upload_ids": [],
    "request_id": "sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H",
    "expected_quote": {
        "unit_price": 3.75,
        "total": 7.5
    }
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/sell/cards\n%s\n{"type":1,"country_id":9,"brand_id":1,"gift_id":1,"quantity":2,"comment":"","cards":"CODE-1\\nCODE-2","card_upload_ids":[],"receipt_upload_ids":[],"request_id":"sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H","expected_quote":{"unit_price":3.75,"total":7.5}}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/sell/cards \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"type":1,"country_id":9,"brand_id":1,"gift_id":1,"quantity":2,"comment":"","cards":"CODE-1\\nCODE-2","card_upload_ids":[],"receipt_upload_ids":[],"request_id":"sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H","expected_quote":{"unit_price":3.75,"total":7.5}}'

Response

{
    "ok": 1,
    "data": {
        "order_id": 75791,
        "uuid": "455f...",
        "status": 0,
        "amount": 3.75,
        "total": 7.5,
        "net_total": 0,
        "quantity": 2,
        "files": {
            "cards": [],
            "receipts": []
        },
        "request_id": "sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H",
        "duplicate": false
    }
}

Works like /sell/cards, using platform_id instead of brand_id. If the platform has receipt_required enabled, include receipt_upload_ids; missing receipts return 4012.

Send request_id (32 to 128 characters of [A-Za-z0-9_-], or the Idempotency-Key header) to make retries safe. A repeat with the same id and the same body returns the stored answer with duplicate: true and creates nothing; the same id with a different body returns 409 with error 4065. When you cannot tell whether a request arrived, ask GET /sell/requests: an id it has never seen is cancelled from then on, and a create with it returns 409 with error 4090. Two requests of one account at the same moment wait for each other; after five seconds the second returns 4091.

Add expected_quote with the unit_price and total from POST /sell/quote to sell only at that price: if the price moved, nothing is created and the answer is 200 with status: "price_changed" and the fresh quote. The acting account needs a confirmed e-mail address; otherwise the call answers 403 with error 4086.

POSThttps://api.cytrongift.com/v1/sell/games

Body

{
    "type": 1,
    "country_id": 9,
    "platform_id": 1,
    "gift_id": 1,
    "quantity": 1,
    "cards": "KEY-1",
    "receipt_upload_ids": [],
    "request_id": "sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H",
    "expected_quote": {
        "unit_price": 3.75,
        "total": 7.5
    }
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/sell/games\n%s\n{"type":1,"country_id":9,"platform_id":1,"gift_id":1,"quantity":1,"cards":"KEY-1","receipt_upload_ids":[],"request_id":"sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H","expected_quote":{"unit_price":3.75,"total":7.5}}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/sell/games \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"type":1,"country_id":9,"platform_id":1,"gift_id":1,"quantity":1,"cards":"KEY-1","receipt_upload_ids":[],"request_id":"sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H","expected_quote":{"unit_price":3.75,"total":7.5}}'

Response

{
    "ok": 1,
    "data": {
        "order_id": 75792,
        "uuid": "9a1c...",
        "status": 0,
        "amount": 12,
        "total": 12,
        "net_total": 0,
        "quantity": 1,
        "files": {
            "cards": [],
            "receipts": []
        },
        "request_id": "sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H",
        "duplicate": false
    }
}

Prices one selection for your account without opening an order: the payout per item (unit_price), the order before the bonus (subtotal) and with your bonus level applied (total, bonus_percent, bonus_amount), in USD.

Set kind to cards or games. item_id is the card or game, category_id its brand or platform and country_id its region, as /catalog/cards and /catalog/games list them; quantity is 1 to 1000. An item that is no longer on sale returns 4062; ids that do not belong together return 4063 with the expected ids in extra.

Pass unit_price and total back as expected_quote when you create the order, so a price that moved in between is reported instead of accepted. The acting account needs a confirmed e-mail address; otherwise the call answers 403 with error 4086.

POSThttps://api.cytrongift.com/v1/sell/quote

Body

{
    "kind": "cards",
    "item_id": 1,
    "category_id": 1,
    "country_id": 9,
    "quantity": 2
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/sell/quote\n%s\n{"kind":"cards","item_id":1,"category_id":1,"country_id":9,"quantity":2}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/sell/quote \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"kind":"cards","item_id":1,"category_id":1,"country_id":9,"quantity":2}'

Response

{
    "ok": 1,
    "data": {
        "kind": "cards",
        "item_id": 1,
        "category_id": 1,
        "country_id": 9,
        "quantity": 2,
        "unit_price": 3.75,
        "subtotal": 7.5,
        "total": 7.5,
        "bonus_percent": 0,
        "bonus_amount": 0,
        "currency": "USD",
        "symbol": "$",
        "quoted_at": 1793965740
    }
}

Returns what happened to a request_id you sent to POST /sell/cards or POST /sell/games. A known id returns the stored answer of that create with state: "done".

An id the server has never seen returns status: "cancelled" and state: "cancelled", and from that moment a create with it is refused with 4090. So after a timeout, ask here first: either the order exists, or you know for sure it never will and can send the sale again with a new id. A request id has 32 to 128 characters of [A-Za-z0-9_-].

GEThttps://api.cytrongift.com/v1/sell/requests

Query

NameTypeAbout
request_id *stringThe id you sent with the create.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/sell/requests\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/sell/requests \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "order_id": 82482,
        "uuid": "ade8...",
        "status": 0,
        "amount": 3.75,
        "total": 3.75,
        "net_total": 0,
        "quantity": 1,
        "files": {
            "cards": [],
            "receipts": []
        },
        "request_id": "sell_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H",
        "state": "done"
    }
}

Withdrawals

Request payouts and check their status and history.

Set amount to a positive number with up to 2 decimal places. It is deducted from your balance as soon as the request is created. Use amount_type 0 for your main balance or 1 for your referral balance.

Choose a method_id from /catalog/payments with a current rate. The wallet must match the method's format, or you get 4053. Include fio if the method has needs_fio enabled.

Use request_id to make retries safe. It must match [a-zA-Z0-9_-]{16,128}. Repeating the same request with the same id returns the original record with duplicate: true. Reusing that id with different content returns HTTP 409 with error 4065. If you omit the field, you can pass the value in the Idempotency-Key header instead.

If your balance is too low, you get 4054, with available and requested amounts in extra.

Instead of amount and amount_type you may send balance_source (main or referral): the payout is then the whole balance of that source at the moment of the request, as POST /withdrawal/quote shows it; an empty balance returns 4054. The two forms cannot be mixed.

Add expected_quote with amount, amount_converted, currency, method_currency and method_network to pay out only that: if anything moved, nothing is debited and the answer is 200 with status: "price_changed" and the fresh quote.

A request_id of 32 characters or more also gets a receipt: a retry returns the stored answer with duplicate: true, GET /withdrawal/requests reports its outcome, and an id that lookup cancelled is refused with 4090. Two requests of one account at the same moment wait for each other; after five seconds the second returns 4091. The acting account needs a confirmed e-mail address; otherwise the call answers 403 with error 4086.

The whole-balance form looks like this: {"request_id": "wd_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H4J", "balance_source": "main", "method_id": 2, "wallet": "bc1q...", "expected_quote": {"amount": 25, "amount_converted": 0.00030464, "currency": "USD", "method_currency": "BTC", "method_network": "BTC"}}.

Two-factor authentication. A request made with a user token (Bearer ut_..., a person signed in through POST /auth/identity) for an account with two-factor authentication on must carry totp, the six digits of the authenticator app as a string. Without it the answer is 403 with error 4150 (totp_required), with a wrong or already used code 400 with 4151 (totp_invalid); nothing is debited either way, and the same request_id may be sent again with the code. A code works once: two payouts in a row need two different codes, about 30 seconds apart. The code is asked after every other check, so a refused payout or a price_changed answer does not use it up, and a retry answered from the receipt needs none. Requests signed with an application key, and JWTs of POST /auth, are never asked. GET /account/profile tells in two_factor whether the account has it on. Lock. Five wrong codes of one account within 15 minutes, counted together across the website and every endpoint that asks for a code, lock its second factor until that window ends: the answer is then 429 with error 4156 (totp_locked), retry_after in seconds and a Retry-After header, even for a right code. Show the wait and do not retry before it.

POSThttps://api.cytrongift.com/v1/withdrawal/create

Body

{
    "amount": 10.5,
    "method_id": 2,
    "wallet": "1A1zP1...",
    "fio": "John Doe",
    "amount_type": 0,
    "request_id": "wd_01K1A8T4S7Q2M5N9P3R6"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/withdrawal/create\n%s\n{"amount":10.5,"method_id":2,"wallet":"1A1zP1...","fio":"John Doe","amount_type":0,"request_id":"wd_01K1A8T4S7Q2M5N9P3R6"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/withdrawal/create \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"amount":10.5,"method_id":2,"wallet":"1A1zP1...","fio":"John Doe","amount_type":0,"request_id":"wd_01K1A8T4S7Q2M5N9P3R6"}'

Response

{
    "ok": 1,
    "data": {
        "id": 15870,
        "uuid": "f28f...",
        "status": 0,
        "amount": 10.5,
        "amount_converted": 0.00013169,
        "amount_type": 0,
        "balance_source": "main",
        "method_id": 2,
        "wallet": "1A1zP1...",
        "date_create": 1788605258,
        "request_id": "wd_01K1A8T4S7Q2M5N9P3R6",
        "duplicate": false
    }
}

Returns your payouts, newest first. Each item includes id, uuid, type, status (processing|complete|rejected), status_id, amount, amount_converted, amount_type, wallet, fio, tx_out, date_create, date_result and method.

The method object contains id, currency, name_ru and name_en as they were when the payout was created.

GEThttps://api.cytrongift.com/v1/withdrawal/transactions

Query

NameTypeAbout
idintegerReturn one payout directly in data, without the list wrapper.
typestringmain or referral
cursorintegerReturn items with ids less than this cursor.
limitinteger, default 20Items per page: 1 to 200.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/withdrawal/transactions\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/withdrawal/transactions \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "items": [],
        "limit": 20,
        "cursor": 0,
        "next_cursor": null,
        "filters": {
            "type": null
        }
    }
}

Calculates the payout of the whole balance of one source: balance_source is main or referral, method_id a method from /catalog/payments with a current rate (else 4052). Nothing is reserved.

The answer carries both fresh balances, the method, the amount in USD, the amount_converted in the method currency (8 decimals) and eligible, false when that balance is empty. Pass amount, amount_converted, currency, method.currency and method.network back as expected_quote of POST /withdrawal/create. The acting account needs a confirmed e-mail address; otherwise the call answers 403 with error 4086.

POSThttps://api.cytrongift.com/v1/withdrawal/quote

Body

{
    "balance_source": "main",
    "method_id": 2
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/withdrawal/quote\n%s\n{"balance_source":"main","method_id":2}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/withdrawal/quote \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"balance_source":"main","method_id":2}'

Response

{
    "ok": 1,
    "data": {
        "balance_source": "main",
        "method_id": 2,
        "currency": "USD",
        "symbol": "$",
        "balances": {
            "main": 25,
            "referral": 3
        },
        "method": {
            "id": 2,
            "code": "BTC",
            "currency": "BTC",
            "network": "BTC",
            "name_ru": "Bitcoin",
            "name_en": "Bitcoin",
            "example": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
            "rate_date": 1791997622,
            "needs_fio": false,
            "has_image": true
        },
        "amount": 25,
        "amount_converted": 0.00030464,
        "eligible": true,
        "quoted_at": 1793965801
    }
}

Returns what happened to a request_id of 32 to 128 characters you sent to POST /withdrawal/create, with your fresh balances. A known id returns the payout answer with state: "done", also for a payout made before receipts existed.

An id the server has never seen returns status: "cancelled", and from then on a create with it is refused with 4090, so after a timeout you know for sure whether money left the balance.

GEThttps://api.cytrongift.com/v1/withdrawal/requests

Query

NameTypeAbout
request_id *stringThe id you sent with the create.

Request

TS=$(date +%s)
SIG=$(printf 'GET\n/withdrawal/requests\n%s\n' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl https://api.cytrongift.com/v1/withdrawal/requests \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Response

{
    "ok": 1,
    "data": {
        "id": 18525,
        "uuid": "9d71...",
        "status": 0,
        "amount": 25,
        "amount_converted": 0.00030464,
        "amount_type": 0,
        "balance_source": "main",
        "method_id": 2,
        "wallet": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
        "date_create": 1793965809,
        "request_id": "wd_01K9ZP4M3R7T2W6Y8B5C1D9F0G3H4J",
        "state": "done",
        "balances": {
            "main": 0,
            "referral": 3
        }
    }
}

Support

Create support tickets you can also follow in your account.

Creates a ticket you can also follow in your account on the website. If you omit name or email, the values from your profile are used.

The subject must be 3 to 64 characters; the message, 20 to 8192. The same flood protection as on the website applies (3011). The response includes code for guest access to the conversation.

POSThttps://api.cytrongift.com/v1/support/create

Body

{
    "subject": "Question",
    "message": "At least twenty characters of text.",
    "name": "John Doe",
    "email": "[email protected]",
    "lang": "en"
}

Request

TS=$(date +%s)
SIG=$(printf 'POST\n/support/create\n%s\n{"subject":"Question","message":"At least twenty characters of text.","name":"John Doe","email":"[email protected]","lang":"en"}' "$TS" | openssl dgst -sha256 -hmac "$CYTRON_API_SECRET" | awk '{print $NF}')
curl -X POST https://api.cytrongift.com/v1/support/create \
  -H "X-Api-Key: $CYTRON_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" --data-raw '{"subject":"Question","message":"At least twenty characters of text.","name":"John Doe","email":"[email protected]","lang":"en"}'

Response

{
    "ok": 1,
    "data": {
        "ticket_id": 1888,
        "code": "b296...",
        "status": 0,
        "name": "John Doe",
        "email": "[email protected]",
        "subject": "Question",
        "date": 1788605297
    }
}

Clients

Pick a client and try your first request. Each is a single file with no external dependencies. It signs requests, gets a bearer token and reads your balance using both methods. Set CYTRON_API_KEY and CYTRON_API_SECRET, then run the file. To use a different base URL, pass it as the first argument.

<?php
/**
 * Cytrongift API client in plain PHP (curl, no dependencies).
 *
 *   CYTRON_API_KEY=ck_... CYTRON_API_SECRET=cs_... php client.php [base_url]
 *
 * Signs every request with the application key, exchanges the signature for a Bearer token
 * and reads the balance twice: once over the signature, once over the token.
 */

final class CytronApi {

	private string $base;
	private string $key;
	private string $secret;
	private string $token = '';

	public function __construct(string $base, string $key, string $secret) {
		$this->base 	= rtrim($base, '/');
		$this->key 		= $key;
		$this->secret 	= $secret;
	}

	/**
	 * One request. The signature covers METHOD, PATH (without /v1), TIMESTAMP and the raw body.
	 *
	 * @return array the decoded envelope
	 */
	public function request(string $method, string $path, ?array $body = null, bool $bearer = false): array {
		$method 	= strtoupper($method);
		$raw 		= $body === null ? '' : json_encode($body, JSON_UNESCAPED_SLASHES);
		$headers 	= ['Accept: application/json'];
		if ($raw !== '') {
			$headers[] = 'Content-Type: application/json';
		}
		if ($bearer && $this->token !== '') {
			$headers[] = 'Authorization: Bearer '.$this->token;
		}
		else {
			$ts 		= (string) time();
			$signature 	= hash_hmac('sha256', $method."\n".'/'.ltrim(parse_url($path, PHP_URL_PATH), '/')."\n".$ts."\n".$raw, $this->secret);
			$headers[] 	= 'X-Api-Key: '.$this->key;
			$headers[] 	= 'X-Timestamp: '.$ts;
			$headers[] 	= 'X-Signature: '.$signature;
		}
		$ch = curl_init($this->base.$path);
		curl_setopt_array($ch, [
			CURLOPT_CUSTOMREQUEST 	=> $method,
			CURLOPT_HTTPHEADER 		=> $headers,
			CURLOPT_POSTFIELDS 		=> $raw === '' ? null : $raw,
			CURLOPT_RETURNTRANSFER 	=> true,
			CURLOPT_TIMEOUT 		=> 30,
		]);
		$answer = curl_exec($ch);
		$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
		curl_close($ch);
		$data = json_decode((string) $answer, true);
		if (!is_array($data)) {
			throw new RuntimeException('HTTP '.$status.': not a JSON envelope');
		}
		return $data;
	}

	/** Exchange the signature for a Bearer token and keep it for later calls. */
	public function auth(int $ttl = 3600): array {
		$answer = $this->request('POST', '/auth', ['ttl' => $ttl]);
		if (!empty($answer['ok'])) {
			$this->token = (string) $answer['data']['access_token'];
		}
		return $answer;
	}
}

if (PHP_SAPI === 'cli' && realpath($argv[0] ?? '') === __FILE__) {
	$cytron = new CytronApi($argv[1] ?? 'https://api.cytrongift.com/v1', (string) getenv('CYTRON_API_KEY'), (string) getenv('CYTRON_API_SECRET'));
	$steps = [
		'health' 		=> $cytron->request('GET', '/health'),
		'config' 		=> $cytron->request('GET', '/config'),
		'stats' 		=> $cytron->request('GET', '/stats'),
		'offers' 		=> $cytron->request('GET', '/catalog/offers?limit=5'),
		'balance' 		=> $cytron->request('GET', '/account/balance'),
		'auth' 			=> $cytron->auth(),
		'balance_jwt' 	=> $cytron->request('GET', '/account/balance', null, true),
	];
	foreach ($steps as $name => $answer) {
		printf("%-12s %s\n", $name, !empty($answer['ok']) ? 'ok' : 'error '.($answer['error']['id'] ?? '?').' '.($answer['error']['desc'] ?? ''));
		if (empty($answer['ok'])) {
			exit(1);
		}
	}
}

Postman

Import the collection and one environment; type your key pair into the environment. Every operation is a request in a folder per tag, and a script on the collection signs each call by the rules of the guide.

Errors

Look up error.id to see what went wrong and what to do next. These descriptions and tips are in English; send Accept-Language: ru for Russian. The error.code field always matches the HTTP status.

JSONCSVXML

3xxx · Authentication and limits

idHTTPMeaning / what to do
3000405HTTP method not supportedCheck which HTTP methods this endpoint accepts.
3001401Authentication requiredSend X-Api-Key, X-Timestamp and X-Signature, or a bearer token in the Authorization header.
3002401Request timestamp is out of rangeSend X-Timestamp as Unix time in seconds, within 300 seconds of the server clock.
3003401Signature does not matchSign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.
3004403API access is disabled for this accountContact support to enable API access.
3005403Account is blockedContact support to review the block.
3006401API key not foundCheck that X-Api-Key matches the key issued in your account settings.
3007401Bearer token is missing or malformedSend the token in this format: Authorization: Bearer {jwt}.
3008401Token has expiredRequest a new token from POST /auth using your HMAC headers.
3009401Invalid tokenThe token signature or payload is invalid. Request a new token from POST /auth.
3010503Token signing key is not configuredWe cannot issue or verify tokens right now. Contact support.
3011429Too many requestsSlow down and wait before retrying. If Retry-After is present, wait the number of seconds it specifies. The default API key limit is 60 requests per minute.
3012403Application key is inactiveThe key was revoked or expired 24 hours after rotation. Create or rotate a key in Apps & API in your account.
3013403Application access is disabledThe application is paused by our team, disabled by its owner or awaiting approval. Check extra for the reason.
3014403Required scope is missingCheck extra for the scope this endpoint needs. Contact support to request access to it.
3015503Key store is not configuredWe cannot read application keys right now. Contact support.
3016401Key belongs to the other addressA sandbox key (cks_) works only on https://sandbox.cytrongift.com/v1, a live key (ck_) only on https://api.cytrongift.com/v1. Check extra.host for the address that answered.

4xxx · Business rules

idHTTPMeaning / what to do
4000415Unsupported content typeUse application/json, or multipart/form-data for POST /uploads/images.
4007404Record not foundCheck the id. There is no matching record in your account.
4008403Record belongs to another accountYou can only read and update records in your own account.
4010403No account linked to these credentialsYour credentials are valid, but they are not linked to an account. Contact support.
4012400Required field is missingCheck extra for the field name and include it in your request.
4013400Invalid JSON bodyCheck the request body. It must be a valid JSON object.
4017400Invalid amountUse a number greater than zero, with no more than 2 decimal places.
4019404User not foundCheck the id. No user matches it.
4052400Payout method not foundChoose a method id from GET /catalog/payments.
4053400Wallet format does not match the payout methodCheck the wallet format for your chosen payout method.
4054400Insufficient fundsThe requested payout is greater than your balance. Reduce the amount and try again.
4059400Invalid email addressCheck the address format, for example [email protected].
4060400Invalid ticket subjectUse 3 to 64 characters for the subject.
4061400Invalid ticket messageUse 20 to 8192 characters for the message.
4062404Gift card or game not foundChoose an item currently accepted for sale from GET /catalog/cards or GET /catalog/games.
4063400Item does not match the selected brand, platform or countryCheck the item in the catalogue and use its brand, platform and country ids.
4064400Card details are missingSend codes in `cards`, or upload card photos first and pass their card_upload_ids.
4065409Idempotency key was used for a different requestUse the same key only when retrying the exact same request. For a new request, use a new key.
4066403File is already attached to an orderOnce a photo is attached to an order, it cannot be deleted through the API.
4067429Too many orders in the last hourWait before trying again. Send one order at a time, with a short pause between requests.
4068409Code is already in an open orderCheck extra for the codes still being processed. Wait for the existing orders to finish instead of resending those codes.
4073400No file receivedSend images in files[] using multipart/form-data.
4074400Unsupported image formatTry a JPEG, PNG or WebP image.
4075400File is too largeCheck extra for the size limit in bytes and upload a smaller file.
4076500Could not save the fileTry uploading it again, or choose another file.
4082400Invalid field valueCheck extra for the field that failed validation.
4084409Could not confirm the linked accountThe account needs to be linked on the website first, or another sign-in is in progress. Check extra for the reason.
4085400Webhook limit reachedDelete a webhook you no longer use before adding another. Check extra for the limit.
4086403E-mail address is not confirmedSelling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail.
4087409E-mail address belongs to another accountUse another address, or sign in on the website with the account that holds this one and link it.
4088429Verification mail was sent recentlyWait the seconds given in extra.retry_after before asking for another mail. At most one a minute and five an hour.
4090409This request id was cancelledA lookup closed this request id before the request arrived, so nothing was created. Send the request again with a new request id.
4091409Another request of this account is in progressWait for the running request to finish, then retry with the same request id.

5xxx · Transport and platform

idHTTPMeaning / what to do
5003503Endpoint is temporarily disabledTry again later.
5004400Invalid endpoint pathCheck the path for characters the router does not accept.
5005404Endpoint not foundCheck the path in the API documentation.
5007500Something went wrong on our endWe could not complete the request. Try again later.
5008503Service is under maintenanceWait the number of seconds in Retry-After, then try again.

Changelog

What changed in the API, newest first: the last eight releases here, every release in changelog.md.

v1.5.4 12 Nov 2026

v1.5.3 12 Nov 2026

v1.5.2 11 Nov 2026

v1.5.1 11 Nov 2026

v1.5.0 11 Nov 2026

v1.4.0 10 Nov 2026

v1.3.0 6 Nov 2026

v1.2.1 30 Oct 2026

Cytrongift API v1.5.4. OpenAPI specification: openapi.json.Powered by Perfecto Web