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/v1Add 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 ) )
PATHis the endpoint path without/v1or the query string, for example/account/balance.TIMESTAMPis Unix time in seconds. It must be within 300 seconds of the server clock, or you get3002.RAW_BODYis the exact body you send, byte for byte. Use an empty string formultipart/form-data.
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/v1The 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
- Open Apps & API in your Cytrongift account and request API access, exactly as for the live API. One approval covers both addresses.
- 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. - 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
- Call
GET /health: on the sandbox it reports"sandbox": true, and every sandbox answer carries the headerX-Sandbox: 1.
What is different
| Area | On the sandbox |
|---|---|
| Balance | Every account starts with 1000 USD of test money. No money moves and nothing is reviewed by a person. |
| Orders and payouts | Settled by the sandbox itself two minutes after creation: most complete, every third is rejected, so both outcomes can be rehearsed. |
| Catalogue | Brands, 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 data | Members, orders and payouts of the live site are never there; the sandbox account is a twin with the same ID. |
| Webhooks | The same deliveries as on the live API, signed the same way, with one more header: X-Sandbox: 1. |
| Limits | 60 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.
Health check
Checks the database and cache. Returns 200 when both respond, or 503 if either check fails.
https://api.cytrongift.com/v1/healthRequest
curl https://api.cytrongift.com/v1/health$answer = $cytron->request('GET', '/health');
print_r($answer['data']);const answer = await cytron.request('GET', '/health');
console.log(answer.data);answer = cytron.request('GET', '/health')
print(answer['data'])env, err := cytron.Request("GET", "/health", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"status": "ok",
"service": "cytrongift-api",
"version": "1.5.4",
"sandbox": false,
"timestamp": 1788605154,
"checks": {
"database": "ok",
"cache": "ok"
}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Service configuration
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.
https://api.cytrongift.com/v1/configRequest
curl https://api.cytrongift.com/v1/config$answer = $cytron->request('GET', '/config');
print_r($answer['data']);const answer = await cytron.request('GET', '/config');
console.log(answer.data);answer = cytron.request('GET', '/config')
print(answer['data'])env, err := cytron.Request("GET", "/config", nil, false)
fmt.Println(string(env.Data)) 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"
}
}
}
}
Bonus tiers
Returns the public table of bonus tiers.
https://api.cytrongift.com/v1/bonusRequest
curl https://api.cytrongift.com/v1/bonus$answer = $cytron->request('GET', '/bonus');
print_r($answer['data']);const answer = await cytron.request('GET', '/bonus');
console.log(answer.data);answer = cytron.request('GET', '/bonus')
print(answer['data'])env, err := cytron.Request("GET", "/bonus", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"levels": [
{
"level": 1,
"threshold": 10000,
"bonus_percent": 0.05
}
]
}
}
Site statistics
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.
https://api.cytrongift.com/v1/statsRequest
curl https://api.cytrongift.com/v1/stats$answer = $cytron->request('GET', '/stats');
print_r($answer['data']);const answer = await cytron.request('GET', '/stats');
console.log(answer.data);answer = cytron.request('GET', '/stats')
print(answer['data'])env, err := cytron.Request("GET", "/stats", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"card_types": 120,
"members": 25000,
"items_sold": 98000,
"referral_rewards": 14250.5,
"currency": "USD",
"symbol": "$"
}
}
Latest sales
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.
https://api.cytrongift.com/v1/sales/latestRequest
curl https://api.cytrongift.com/v1/sales/latest$answer = $cytron->request('GET', '/sales/latest');
print_r($answer['data']);const answer = await cytron.request('GET', '/sales/latest');
console.log(answer.data);answer = cytron.request('GET', '/sales/latest')
print(answer['data'])env, err := cytron.Request("GET", "/sales/latest", nil, false)
fmt.Println(string(env.Data)) 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.
Brands
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.
https://api.cytrongift.com/v1/catalog/brandsRequest
curl https://api.cytrongift.com/v1/catalog/brands$answer = $cytron->request('GET', '/catalog/brands');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/brands');
console.log(answer.data);answer = cytron.request('GET', '/catalog/brands')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/brands", nil, false)
fmt.Println(string(env.Data)) 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
}
}
Platforms
Lists platforms with at least one game currently accepted for sale. Each item includes id, name_ru, name_en, icon, receipt_required and sort.
https://api.cytrongift.com/v1/catalog/platformsRequest
curl https://api.cytrongift.com/v1/catalog/platforms$answer = $cytron->request('GET', '/catalog/platforms');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/platforms');
console.log(answer.data);answer = cytron.request('GET', '/catalog/platforms')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/platforms", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"items": [
{
"id": 1,
"name_ru": "Steam",
"name_en": "Steam",
"icon": "",
"receipt_required": false,
"sort": 1
}
],
"total": 1
}
}
Payout methods
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.
https://api.cytrongift.com/v1/catalog/paymentsRequest
curl https://api.cytrongift.com/v1/catalog/payments$answer = $cytron->request('GET', '/catalog/payments');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/payments');
console.log(answer.data);answer = cytron.request('GET', '/catalog/payments')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/payments", nil, false)
fmt.Println(string(env.Data)) 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
}
}
Gift cards
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.
https://api.cytrongift.com/v1/catalog/cardsQuery
| Name | Type | About |
|---|---|---|
brand_id | integer | Filter by brand id. |
country_id | integer | Filter by country id. |
search | string | Match part of the item name. |
cursor | integer | Return items with ids greater than this cursor. |
limit | integer, default 50 | Items per page: 1 to 500. |
Request
curl https://api.cytrongift.com/v1/catalog/cards$answer = $cytron->request('GET', '/catalog/cards');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/cards');
console.log(answer.data);answer = cytron.request('GET', '/catalog/cards')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/cards", nil, false)
fmt.Println(string(env.Data)) 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": ""
}
}
}
Game keys
Returns a paginated list of game keys. Items have the same fields as gift cards, with platform_id instead of brand_id.
https://api.cytrongift.com/v1/catalog/gamesQuery
| Name | Type | About |
|---|---|---|
platform_id | integer | Filter by platform id. |
country_id | integer | Filter by country id. |
search | string | Match part of the item name. |
cursor | integer | Return items with ids greater than this cursor. |
limit | integer, default 50 | Items per page: 1 to 500. |
Request
curl https://api.cytrongift.com/v1/catalog/games$answer = $cytron->request('GET', '/catalog/games');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/games');
console.log(answer.data);answer = cytron.request('GET', '/catalog/games')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/games", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"items": [],
"limit": 50,
"cursor": 0,
"next_cursor": null,
"filters": []
}
}
Countries by brand or platform
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.
https://api.cytrongift.com/v1/catalog/countriesQuery
| Name | Type | About |
|---|---|---|
brand_id | integer | Brand id. |
platform_id | integer | Platform id. |
Request
curl https://api.cytrongift.com/v1/catalog/countries$answer = $cytron->request('GET', '/catalog/countries');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/countries');
console.log(answer.data);answer = cytron.request('GET', '/catalog/countries')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/countries", nil, false)
fmt.Println(string(env.Data)) 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
}
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
Offers
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.
https://api.cytrongift.com/v1/catalog/offersQuery
| Name | Type | About |
|---|---|---|
offset | integer, default 0 | Rows to skip, default 0. |
limit | integer, default 10 | Page size from 1 to 100, default 10. |
search | string | Part of the English or Russian name, up to 100 characters. |
Request
curl https://api.cytrongift.com/v1/catalog/offers$answer = $cytron->request('GET', '/catalog/offers');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/offers');
console.log(answer.data);answer = cytron.request('GET', '/catalog/offers')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/offers", nil, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
Catalogue image
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.
https://api.cytrongift.com/v1/catalog/imagesQuery
| Name | Type | About |
|---|---|---|
kind * | string | What the id refers to. |
id * | integer | The id of the item. |
Request
curl https://api.cytrongift.com/v1/catalog/images$answer = $cytron->request('GET', '/catalog/images');
print_r($answer['data']);const answer = await cytron.request('GET', '/catalog/images');
console.log(answer.data);answer = cytron.request('GET', '/catalog/images')
print(answer['data'])env, err := cytron.Request("GET", "/catalog/images", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": []
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Auth
Create, refresh and revoke tokens for API access.
Get a bearer token
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.
https://api.cytrongift.com/v1/authBody (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}'$answer = $cytron->request('POST', '/auth', [ 'ttl' => 3600, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/auth', {"ttl":3600});
console.log(answer.data);answer = cytron.request('POST', '/auth', { "ttl": 3600})
print(answer['data'])env, err := cytron.Request("POST", "/auth", map[string]any{"ttl": 3600}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"token_type": "Bearer",
"access_token": "eyJ...",
"expires_in": 3600,
"expires_at": 1788608789,
"merchant_id": 8269
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Get tokens for a verified user
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.
https://api.cytrongift.com/v1/auth/identityBody
{
"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}'$answer = $cytron->request('POST', '/auth/identity', [ '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, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/auth/identity', {"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});
console.log(answer.data);answer = cytron.request('POST', '/auth/identity', { "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})
print(answer['data'])env, err := cytron.Request("POST", "/auth/identity", map[string]any{"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}, false)
fmt.Println(string(env.Data)) 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
}
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4146",
"code": 404,
"desc": "No account for this sign-in yet",
"advice": "Ask the member for an e-mail address and send a sign-in code with POST /auth/identity/claim.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4084",
"code": 409,
"desc": "Could not confirm the linked account",
"advice": "The account needs to be linked on the website first, or another sign-in is in progress. Check extra for the reason.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
Mail a sign-in code to an address
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.
https://api.cytrongift.com/v1/auth/identity/claimBody
{
"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="}'$answer = $cytron->request('POST', '/auth/identity/claim', [ '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=', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/auth/identity/claim', {"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="});
console.log(answer.data);answer = cytron.request('POST', '/auth/identity/claim', { "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="})
print(answer['data'])env, err := cytron.Request("POST", "/auth/identity/claim", map[string]any{"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="}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"sent": true,
"retry_after": 60,
"expires_in": 900
}
}
{
"ok": 0,
"error": {
"id": "4059",
"code": 400,
"desc": "Invalid email address",
"advice": "Check the address format, for example [email protected].",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4088",
"code": 429,
"desc": "Verification mail was sent recently",
"advice": "Wait the seconds given in extra.retry_after before asking for another mail. At most one a minute and five an hour.",
"extra": {}
}
}
Confirm a sign-in code and get tokens
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.
https://api.cytrongift.com/v1/auth/identity/claim/confirmBody
{
"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"}'$answer = $cytron->request('POST', '/auth/identity/claim/confirm', [ 'provider' => 'telegram', 'provider_uid' => '123456789', 'code' => '042137', 'totp' => '918273', 'device' => 'Mini App iPhone', 'client_ip' => '198.51.100.7', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/auth/identity/claim/confirm', {"provider":"telegram","provider_uid":"123456789","code":"042137","totp":"918273","device":"Mini App iPhone","client_ip":"198.51.100.7"});
console.log(answer.data);answer = cytron.request('POST', '/auth/identity/claim/confirm', { "provider": "telegram", "provider_uid": "123456789", "code": "042137", "totp": "918273", "device": "Mini App iPhone", "client_ip": "198.51.100.7"})
print(answer['data'])env, err := cytron.Request("POST", "/auth/identity/claim/confirm", map[string]any{"provider": "telegram","provider_uid": "123456789","code": "042137","totp": "918273","device": "Mini App iPhone","client_ip": "198.51.100.7"}, false)
fmt.Println(string(env.Data)) 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]"
}
}
{
"ok": 0,
"error": {
"id": "4151",
"code": 400,
"desc": "The authenticator code is not correct",
"advice": "Ask for the current six digits from the authenticator app; a code works once, so wait for the next one after it was used.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4150",
"code": 403,
"desc": "A code from the authenticator app is needed",
"advice": "The account has two-factor authentication on. Ask the member for the six digits from their authenticator app and send the same request again with `totp`.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4142",
"code": 409,
"desc": "The accounts need a manual review",
"advice": "The accounts were not merged automatically because of their history or balance. Contact support; the link request is kept for the operator. Check extra for the reasons.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4149",
"code": 410,
"desc": "The sign-in code has expired",
"advice": "Ask for a new code: a code works for 15 minutes, once, and only the latest one.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4156",
"code": 429,
"desc": "Too many wrong authenticator codes",
"advice": "Two-factor authentication of this account is locked for a while after five wrong codes in fifteen minutes; even a right code is refused until then. Wait the seconds given in extra.retry_after.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4145",
"code": 503,
"desc": "The account is busy",
"advice": "Another change to this account is in progress. Try again in a few seconds.",
"extra": {}
}
}
Refresh user tokens
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.
https://api.cytrongift.com/v1/auth/refreshBody
{
"refresh_token": "rt_...",
"ttl": 3600
}
Request
curl https://api.cytrongift.com/v1/auth/refresh$answer = $cytron->request('POST', '/auth/refresh', [ 'refresh_token' => 'rt_...', 'ttl' => 3600, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/auth/refresh', {"refresh_token":"rt_...","ttl":3600});
console.log(answer.data);answer = cytron.request('POST', '/auth/refresh', { "refresh_token": "rt_...", "ttl": 3600})
print(answer['data'])env, err := cytron.Request("POST", "/auth/refresh", map[string]any{"refresh_token": "rt_...","ttl": 3600}, false)
fmt.Println(string(env.Data)) 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"
]
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3009",
"code": 401,
"desc": "Invalid token",
"advice": "The token signature or payload is invalid. Request a new token from POST /auth.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Revoke a user token
Immediately revokes the opaque user token used for this request. JWTs cannot be revoked through this endpoint and return 4082.
https://api.cytrongift.com/v1/auth/logoutBody
[]
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 '[]'$answer = $cytron->request('POST', '/auth/logout', [ ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/auth/logout', []);
console.log(answer.data);answer = cytron.request('POST', '/auth/logout', [])
print(answer['data'])env, err := cytron.Request("POST", "/auth/logout", map[string]any[], false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"revoked": true
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
Start linking Telegram to a site account
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.
https://api.cytrongift.com/v1/identities/link/startBody (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"}'$answer = $cytron->request('POST', '/identities/link/start', [ 'purpose' => 'link', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/identities/link/start', {"purpose":"link"});
console.log(answer.data);answer = cytron.request('POST', '/identities/link/start', { "purpose": "link"})
print(answer['data'])env, err := cytron.Request("POST", "/identities/link/start", map[string]any{"purpose": "link"}, false)
fmt.Println(string(env.Data)) 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"
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4140",
"code": 409,
"desc": "Could not link the accounts",
"advice": "Follow the account linking instructions. Your accounts and balances have not been merged.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Link status
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.
https://api.cytrongift.com/v1/identities/link/statusBody
{
"id": "4cfd03147dc461f0a41324ac5cce8fef",
"secret": "9f2c...64 hex characters"
}
Request
curl https://api.cytrongift.com/v1/identities/link/status$answer = $cytron->request('POST', '/identities/link/status', [ 'id' => '4cfd03147dc461f0a41324ac5cce8fef', 'secret' => '9f2c...64 hex characters', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/identities/link/status', {"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"9f2c...64 hex characters"});
console.log(answer.data);answer = cytron.request('POST', '/identities/link/status', { "id": "4cfd03147dc461f0a41324ac5cce8fef", "secret": "9f2c...64 hex characters"})
print(answer['data'])env, err := cytron.Request("POST", "/identities/link/status", map[string]any{"id": "4cfd03147dc461f0a41324ac5cce8fef","secret": "9f2c...64 hex characters"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"purpose": "link",
"status": "approved",
"account": {
"id": "8269",
"display_name": "Ada Lovelace"
}
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4143",
"code": 410,
"desc": "The link request has expired",
"advice": "Start a new link request and confirm it on the website within 10 minutes.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
Cancel a link
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.
https://api.cytrongift.com/v1/identities/link/cancelBody
{
"id": "4cfd03147dc461f0a41324ac5cce8fef",
"secret": "9f2c...64 hex characters"
}
Request
curl https://api.cytrongift.com/v1/identities/link/cancel$answer = $cytron->request('POST', '/identities/link/cancel', [ 'id' => '4cfd03147dc461f0a41324ac5cce8fef', 'secret' => '9f2c...64 hex characters', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/identities/link/cancel', {"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"9f2c...64 hex characters"});
console.log(answer.data);answer = cytron.request('POST', '/identities/link/cancel', { "id": "4cfd03147dc461f0a41324ac5cce8fef", "secret": "9f2c...64 hex characters"})
print(answer['data'])env, err := cytron.Request("POST", "/identities/link/cancel", map[string]any{"id": "4cfd03147dc461f0a41324ac5cce8fef","secret": "9f2c...64 hex characters"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"cancelled": true
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4143",
"code": 410,
"desc": "The link request has expired",
"advice": "Start a new link request and confirm it on the website within 10 minutes.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
What completing a link would do
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.
https://api.cytrongift.com/v1/identities/link/assessmentBody
{
"id": "4cfd03147dc461f0a41324ac5cce8fef",
"secret": "9f2c...64 hex characters"
}
Request
curl https://api.cytrongift.com/v1/identities/link/assessment$answer = $cytron->request('POST', '/identities/link/assessment', [ 'id' => '4cfd03147dc461f0a41324ac5cce8fef', 'secret' => '9f2c...64 hex characters', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/identities/link/assessment', {"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"9f2c...64 hex characters"});
console.log(answer.data);answer = cytron.request('POST', '/identities/link/assessment', { "id": "4cfd03147dc461f0a41324ac5cce8fef", "secret": "9f2c...64 hex characters"})
print(answer['data'])env, err := cytron.Request("POST", "/identities/link/assessment", map[string]any{"id": "4cfd03147dc461f0a41324ac5cce8fef","secret": "9f2c...64 hex characters"}, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4142",
"code": 409,
"desc": "The accounts need a manual review",
"advice": "The accounts were not merged automatically because of their history or balance. Contact support; the link request is kept for the operator. Check extra for the reasons.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4143",
"code": 410,
"desc": "The link request has expired",
"advice": "Start a new link request and confirm it on the website within 10 minutes.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
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.
https://api.cytrongift.com/v1/identities/link/completeBody
{
"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}'$answer = $cytron->request('POST', '/identities/link/complete', [ 'id' => '4cfd03147dc461f0a41324ac5cce8fef', 'secret' => '9f2c...64 hex characters', 'device' => 'Mini App iPhone', 'ttl' => 3600, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/identities/link/complete', {"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"9f2c...64 hex characters","device":"Mini App iPhone","ttl":3600});
console.log(answer.data);answer = cytron.request('POST', '/identities/link/complete', { "id": "4cfd03147dc461f0a41324ac5cce8fef", "secret": "9f2c...64 hex characters", "device": "Mini App iPhone", "ttl": 3600})
print(answer['data'])env, err := cytron.Request("POST", "/identities/link/complete", map[string]any{"id": "4cfd03147dc461f0a41324ac5cce8fef","secret": "9f2c...64 hex characters","device": "Mini App iPhone","ttl": 3600}, false)
fmt.Println(string(env.Data)) 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
}
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4142",
"code": 409,
"desc": "The accounts need a manual review",
"advice": "The accounts were not merged automatically because of their history or balance. Contact support; the link request is kept for the operator. Check extra for the reasons.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4143",
"code": 410,
"desc": "The link request has expired",
"advice": "Start a new link request and confirm it on the website within 10 minutes.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Approve a link on the website
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.
https://api.cytrongift.com/v1/identities/link/websiteBody
{
"id": "4cfd03147dc461f0a41324ac5cce8fef",
"secret": "5be1...64 hex characters",
"approve": true
}
Request
curl https://api.cytrongift.com/v1/identities/link/website$answer = $cytron->request('POST', '/identities/link/website', [ 'id' => '4cfd03147dc461f0a41324ac5cce8fef', 'secret' => '5be1...64 hex characters', 'approve' => true, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/identities/link/website', {"id":"4cfd03147dc461f0a41324ac5cce8fef","secret":"5be1...64 hex characters","approve":true});
console.log(answer.data);answer = cytron.request('POST', '/identities/link/website', { "id": "4cfd03147dc461f0a41324ac5cce8fef", "secret": "5be1...64 hex characters", "approve": True})
print(answer['data'])env, err := cytron.Request("POST", "/identities/link/website", map[string]any{"id": "4cfd03147dc461f0a41324ac5cce8fef","secret": "5be1...64 hex characters","approve": true}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"purpose": "link",
"status": "approved",
"account": {
"id": "8269",
"display_name": "Ada Lovelace"
},
"telegram": {
"id": "123456789",
"display_name": "Ada"
}
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4140",
"code": 409,
"desc": "Could not link the accounts",
"advice": "Follow the account linking instructions. Your accounts and balances have not been merged.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4143",
"code": 410,
"desc": "The link request has expired",
"advice": "Start a new link request and confirm it on the website within 10 minutes.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Account
Read your balance, orders and bonus level, update your profile, manage webhooks.
Balance
Returns your current account balance, read directly from the account record.
https://api.cytrongift.com/v1/account/balanceRequest
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"$answer = $cytron->request('GET', '/account/balance');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/balance');
console.log(answer.data);answer = cytron.request('GET', '/account/balance')
print(answer['data'])env, err := cytron.Request("GET", "/account/balance", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"balance": 250,
"referrals_earned": 0,
"referrals_count": 0,
"currency_code": "USD",
"currency_symbol": "$"
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Bonus level
Returns your bonus level based on completed payouts. next_level is null if you have reached the highest tier.
https://api.cytrongift.com/v1/account/bonusRequest
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"$answer = $cytron->request('GET', '/account/bonus');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/bonus');
console.log(answer.data);answer = cytron.request('GET', '/account/bonus')
print(answer['data'])env, err := cytron.Request("GET", "/account/bonus", nil, false)
fmt.Println(string(env.Data)) 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
}
]
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Order totals
Returns order totals grouped by status. processing includes statuses 0 and 3.
https://api.cytrongift.com/v1/account/analyticsRequest
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"$answer = $cytron->request('GET', '/account/analytics');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/analytics');
console.log(answer.data);answer = cytron.request('GET', '/account/analytics')
print(answer['data'])env, err := cytron.Request("GET", "/account/analytics", nil, false)
fmt.Println(string(env.Data)) 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
}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Orders
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.
https://api.cytrongift.com/v1/account/transactionsQuery
| Name | Type | About |
|---|---|---|
id | integer | Return one order directly in data, without the list wrapper. |
type | string | cards or games |
cursor | integer | Return items with ids less than this cursor. |
limit | integer, default 20 | Items 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"$answer = $cytron->request('GET', '/account/transactions');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/transactions');
console.log(answer.data);answer = cytron.request('GET', '/account/transactions')
print(answer['data'])env, err := cytron.Request("GET", "/account/transactions", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"items": [],
"limit": 20,
"cursor": 0,
"next_cursor": null,
"filters": {
"type": null
}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Order image
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.
https://api.cytrongift.com/v1/account/order-imageQuery
| Name | Type | About |
|---|---|---|
token * | string | The 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"$answer = $cytron->request('GET', '/account/order-image');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/order-image');
console.log(answer.data);answer = cytron.request('GET', '/account/order-image')
print(answer['data'])env, err := cytron.Request("GET", "/account/order-image", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": []
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Profile settings
Returns your profile fields.
https://api.cytrongift.com/v1/account/settingsRequest
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"$answer = $cytron->request('GET', '/account/settings');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/settings');
console.log(answer.data);answer = cytron.request('GET', '/account/settings')
print(answer['data'])env, err := cytron.Request("GET", "/account/settings", nil, false)
fmt.Println(string(env.Data)) 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": ""
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Update profile settings
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.
https://api.cytrongift.com/v1/account/settingsBody
{
"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"}'$answer = $cytron->request('PATCH', '/account/settings', [ 'city' => 'Berlin', 'telegram' => '@seller', ]);
print_r($answer['data']);const answer = await cytron.request('PATCH', '/account/settings', {"city":"Berlin","telegram":"@seller"});
console.log(answer.data);answer = cytron.request('PATCH', '/account/settings', { "city": "Berlin", "telegram": "@seller"})
print(answer['data'])env, err := cytron.Request("PATCH", "/account/settings", map[string]any{"city": "Berlin","telegram": "@seller"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"updated": true,
"settings": {
"id": 8269,
"city": "Berlin"
}
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Webhooks
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.
https://api.cytrongift.com/v1/account/webhooksRequest
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"$answer = $cytron->request('GET', '/account/webhooks');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/webhooks');
console.log(answer.data);answer = cytron.request('GET', '/account/webhooks')
print(answer['data'])env, err := cytron.Request("GET", "/account/webhooks", nil, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Add a webhook
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.
https://api.cytrongift.com/v1/account/webhooksBody
{
"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"}'$answer = $cytron->request('POST', '/account/webhooks', [ 'url' => 'https://partner.example.com/cytrongift/hook', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/webhooks', {"url":"https://partner.example.com/cytrongift/hook"});
console.log(answer.data);answer = cytron.request('POST', '/account/webhooks', { "url": "https://partner.example.com/cytrongift/hook"})
print(answer['data'])env, err := cytron.Request("POST", "/account/webhooks", map[string]any{"url": "https://partner.example.com/cytrongift/hook"}, false)
fmt.Println(string(env.Data)) 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"
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4008",
"code": 403,
"desc": "Record belongs to another account",
"advice": "You can only read and update records in your own account.",
"extra": {}
}
}
Delete a webhook
Drops one address of your account; deliveries still waiting for it are cancelled. An unknown id, or one held by another account, returns 4007.
https://api.cytrongift.com/v1/account/webhooks/deleteBody
{
"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}'$answer = $cytron->request('POST', '/account/webhooks/delete', [ 'id' => 12, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/webhooks/delete', {"id":12});
console.log(answer.data);answer = cytron.request('POST', '/account/webhooks/delete', { "id": 12})
print(answer['data'])env, err := cytron.Request("POST", "/account/webhooks/delete", map[string]any{"id": 12}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"id": 12,
"deleted": true
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Profile
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.
https://api.cytrongift.com/v1/account/profileRequest
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"$answer = $cytron->request('GET', '/account/profile');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/profile');
console.log(answer.data);answer = cytron.request('GET', '/account/profile')
print(answer['data'])env, err := cytron.Request("GET", "/account/profile", nil, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Add an e-mail address
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.
https://api.cytrongift.com/v1/account/emailBody
{
"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]"}'$answer = $cytron->request('POST', '/account/email', [ 'email' => '[email protected]', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/email', {"email":"[email protected]"});
console.log(answer.data);answer = cytron.request('POST', '/account/email', { "email": "[email protected]"})
print(answer['data'])env, err := cytron.Request("POST", "/account/email", map[string]any{"email": "[email protected]"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"email": "[email protected]",
"email_verified": false,
"sent": true,
"retry_after": 60
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4087",
"code": 409,
"desc": "E-mail address belongs to another account",
"advice": "Use another address, or sign in on the website with the account that holds this one and link it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4088",
"code": 429,
"desc": "Verification mail was sent recently",
"advice": "Wait the seconds given in extra.retry_after before asking for another mail. At most one a minute and five an hour.",
"extra": {}
}
}
Resend the verification mail
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.
https://api.cytrongift.com/v1/account/email/resendBody (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 '[]'$answer = $cytron->request('POST', '/account/email/resend', [ ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/email/resend', []);
console.log(answer.data);answer = cytron.request('POST', '/account/email/resend', [])
print(answer['data'])env, err := cytron.Request("POST", "/account/email/resend", map[string]any[], false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"email": "[email protected]",
"email_verified": false,
"sent": true,
"retry_after": 60
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4088",
"code": 429,
"desc": "Verification mail was sent recently",
"advice": "Wait the seconds given in extra.retry_after before asking for another mail. At most one a minute and five an hour.",
"extra": {}
}
}
Mail a one-time code
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.
https://api.cytrongift.com/v1/account/email/codeBody
{
"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"}'$answer = $cytron->request('POST', '/account/email/code', [ 'purpose' => 'pin_reset', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/email/code', {"purpose":"pin_reset"});
console.log(answer.data);answer = cytron.request('POST', '/account/email/code', { "purpose": "pin_reset"})
print(answer['data'])env, err := cytron.Request("POST", "/account/email/code", map[string]any{"purpose": "pin_reset"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"sent": true,
"email": "d***@mail.com",
"expires_in": 900,
"retry_after": 60
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4158",
"code": 429,
"desc": "The code mail was sent recently",
"advice": "Wait the seconds given in extra.retry_after before asking for another code. At most one mail a minute and three an hour.",
"extra": {}
}
}
Confirm a mailed code
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.
https://api.cytrongift.com/v1/account/email/code/confirmBody
{
"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"}'$answer = $cytron->request('POST', '/account/email/code/confirm', [ 'purpose' => 'pin_reset', 'code' => '402518', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/email/code/confirm', {"purpose":"pin_reset","code":"402518"});
console.log(answer.data);answer = cytron.request('POST', '/account/email/code/confirm', { "purpose": "pin_reset", "code": "402518"})
print(answer['data'])env, err := cytron.Request("POST", "/account/email/code/confirm", map[string]any{"purpose": "pin_reset","code": "402518"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"verified": true
}
}
{
"ok": 0,
"error": {
"id": "4159",
"code": 400,
"desc": "The code is not correct",
"advice": "Ask the member to check the six digits from the latest mail; extra.attempts_left says how many tries remain before the code stops working.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4160",
"code": 409,
"desc": "No live code",
"advice": "The code was never sent, has expired, was already used, was replaced by a newer mail or ran out of tries. Ask for a new one with POST /account/email/code.",
"extra": {}
}
}
Two-factor state
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.
https://api.cytrongift.com/v1/account/2faRequest
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"$answer = $cytron->request('GET', '/account/2fa');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/2fa');
console.log(answer.data);answer = cytron.request('GET', '/account/2fa')
print(answer['data'])env, err := cytron.Request("GET", "/account/2fa", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"enabled": false
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Start a two-factor setup
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.
https://api.cytrongift.com/v1/account/2fa/setupBody (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 '[]'$answer = $cytron->request('POST', '/account/2fa/setup', [ ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/2fa/setup', []);
console.log(answer.data);answer = cytron.request('POST', '/account/2fa/setup', [])
print(answer['data'])env, err := cytron.Request("POST", "/account/2fa/setup", map[string]any[], false)
fmt.Println(string(env.Data)) 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>"
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4152",
"code": 409,
"desc": "Two-factor authentication is already on",
"advice": "Switch it off with POST /account/2fa/disable and a live code before starting a new setup.",
"extra": {}
}
}
Switch two-factor on
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.
https://api.cytrongift.com/v1/account/2fa/enableBody
{
"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"}'$answer = $cytron->request('POST', '/account/2fa/enable', [ 'code' => '918273', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/2fa/enable', {"code":"918273"});
console.log(answer.data);answer = cytron.request('POST', '/account/2fa/enable', { "code": "918273"})
print(answer['data'])env, err := cytron.Request("POST", "/account/2fa/enable", map[string]any{"code": "918273"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"enabled": true
}
}
{
"ok": 0,
"error": {
"id": "4151",
"code": 400,
"desc": "The authenticator code is not correct",
"advice": "Ask for the current six digits from the authenticator app; a code works once, so wait for the next one after it was used.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4153",
"code": 409,
"desc": "No two-factor setup is waiting",
"advice": "Start with POST /account/2fa/setup, add the key to an authenticator app, then send its first code.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4156",
"code": 429,
"desc": "Too many wrong authenticator codes",
"advice": "Two-factor authentication of this account is locked for a while after five wrong codes in fifteen minutes; even a right code is refused until then. Wait the seconds given in extra.retry_after.",
"extra": {}
}
}
Switch two-factor off
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.
https://api.cytrongift.com/v1/account/2fa/disableBody
{
"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"}'$answer = $cytron->request('POST', '/account/2fa/disable', [ 'code' => '918273', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/2fa/disable', {"code":"918273"});
console.log(answer.data);answer = cytron.request('POST', '/account/2fa/disable', { "code": "918273"})
print(answer['data'])env, err := cytron.Request("POST", "/account/2fa/disable", map[string]any{"code": "918273"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"enabled": false
}
}
{
"ok": 0,
"error": {
"id": "4151",
"code": 400,
"desc": "The authenticator code is not correct",
"advice": "Ask for the current six digits from the authenticator app; a code works once, so wait for the next one after it was used.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4156",
"code": 429,
"desc": "Too many wrong authenticator codes",
"advice": "Two-factor authentication of this account is locked for a while after five wrong codes in fifteen minutes; even a right code is refused until then. Wait the seconds given in extra.retry_after.",
"extra": {}
}
}
Check an authenticator code
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.
https://api.cytrongift.com/v1/account/2fa/verifyBody
{
"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"}'$answer = $cytron->request('POST', '/account/2fa/verify', [ 'code' => '918273', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/2fa/verify', {"code":"918273"});
console.log(answer.data);answer = cytron.request('POST', '/account/2fa/verify', { "code": "918273"})
print(answer['data'])env, err := cytron.Request("POST", "/account/2fa/verify", map[string]any{"code": "918273"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"verified": true
}
}
{
"ok": 0,
"error": {
"id": "4151",
"code": 400,
"desc": "The authenticator code is not correct",
"advice": "Ask for the current six digits from the authenticator app; a code works once, so wait for the next one after it was used.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4157",
"code": 409,
"desc": "Two-factor authentication is off",
"advice": "The account has no authenticator app to ask. Use another proof, such as POST /account/email/code, or switch two-factor on first.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4156",
"code": 429,
"desc": "Too many wrong authenticator codes",
"advice": "Two-factor authentication of this account is locked for a while after five wrong codes in fifteen minutes; even a right code is refused until then. Wait the seconds given in extra.retry_after.",
"extra": {}
}
}
Mail the first website password link
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.
https://api.cytrongift.com/v1/account/password/setupBody (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 '[]'$answer = $cytron->request('POST', '/account/password/setup', [ ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/password/setup', []);
console.log(answer.data);answer = cytron.request('POST', '/account/password/setup', [])
print(answer['data'])env, err := cytron.Request("POST", "/account/password/setup", map[string]any[], false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"sent": true
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4154",
"code": 409,
"desc": "The account already has a website password",
"advice": "Use the password recovery of the website to change it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4155",
"code": 429,
"desc": "The password mail was sent recently",
"advice": "Wait the seconds given in extra.retry_after before asking for another mail. At most one a minute and three an hour.",
"extra": {}
}
}
History
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.
https://api.cytrongift.com/v1/account/historyQuery
| Name | Type | About |
|---|---|---|
type | string, default all | all, cards, games or withdrawals |
cursor | string | The 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"$answer = $cytron->request('GET', '/account/history');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/history');
console.log(answer.data);answer = cytron.request('GET', '/account/history')
print(answer['data'])env, err := cytron.Request("GET", "/account/history", nil, false)
fmt.Println(string(env.Data)) 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": "$"
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
History item
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.
https://api.cytrongift.com/v1/account/history/itemQuery
| Name | Type | About |
|---|---|---|
kind * | string | cards, games or withdrawals |
id * | string | The id of the history row. |
balance_source | string | main 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"$answer = $cytron->request('GET', '/account/history/item');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/history/item');
console.log(answer.data);answer = cytron.request('GET', '/account/history/item')
print(answer['data'])env, err := cytron.Request("GET", "/account/history/item", nil, false)
fmt.Println(string(env.Data)) 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"
}
]
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Earnings summary
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.
https://api.cytrongift.com/v1/account/summaryRequest
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"$answer = $cytron->request('GET', '/account/summary');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/summary');
console.log(answer.data);answer = cytron.request('GET', '/account/summary')
print(answer['data'])env, err := cytron.Request("GET", "/account/summary", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"sales_earned": 412.5,
"referral_earned": 12.4,
"cashflow": 424.9,
"currency": "USD",
"symbol": "$"
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Referral programme
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.
https://api.cytrongift.com/v1/account/referralsRequest
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"$answer = $cytron->request('GET', '/account/referrals');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/referrals');
console.log(answer.data);answer = cytron.request('GET', '/account/referrals')
print(answer['data'])env, err := cytron.Request("GET", "/account/referrals", nil, false)
fmt.Println(string(env.Data)) 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"
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Referral history
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.
https://api.cytrongift.com/v1/account/referrals/historyQuery
| Name | Type | About |
|---|---|---|
type | string, default all | all, referrals or withdrawals |
cursor | string | The 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"$answer = $cytron->request('GET', '/account/referrals/history');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/referrals/history');
console.log(answer.data);answer = cytron.request('GET', '/account/referrals/history')
print(answer['data'])env, err := cytron.Request("GET", "/account/referrals/history", nil, false)
fmt.Println(string(env.Data)) 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": "$"
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Telegram notification switch
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.
https://api.cytrongift.com/v1/account/notificationsRequest
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"$answer = $cytron->request('GET', '/account/notifications');
print_r($answer['data']);const answer = await cytron.request('GET', '/account/notifications');
console.log(answer.data);answer = cytron.request('GET', '/account/notifications')
print(answer['data'])env, err := cytron.Request("GET", "/account/notifications", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"enabled": false,
"revision": 0
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4144",
"code": 409,
"desc": "No Telegram account is connected",
"advice": "Sign in through Telegram first, then try again.",
"extra": {}
}
}
Turn Telegram notifications on or off
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.
https://api.cytrongift.com/v1/account/notificationsBody
{
"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}'$answer = $cytron->request('PATCH', '/account/notifications', [ 'enabled' => true, 'revision' => 0, ]);
print_r($answer['data']);const answer = await cytron.request('PATCH', '/account/notifications', {"enabled":true,"revision":0});
console.log(answer.data);answer = cytron.request('PATCH', '/account/notifications', { "enabled": True, "revision": 0})
print(answer['data'])env, err := cytron.Request("PATCH", "/account/notifications", map[string]any{"enabled": true,"revision": 0}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"enabled": true,
"revision": 1
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4141",
"code": 409,
"desc": "Notification settings have changed",
"advice": "Reload the current settings and try again.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4145",
"code": 503,
"desc": "The account is busy",
"advice": "Another change to this account is in progress. Try again in a few seconds.",
"extra": {}
}
}
Report a security event
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.
https://api.cytrongift.com/v1/account/notifications/eventBody
{
"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"}'$answer = $cytron->request('POST', '/account/notifications/event', [ 'event' => 'pin_reset', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/account/notifications/event', {"event":"pin_reset"});
console.log(answer.data);answer = cytron.request('POST', '/account/notifications/event', { "event": "pin_reset"})
print(answer['data'])env, err := cytron.Request("POST", "/account/notifications/event", map[string]any{"event": "pin_reset"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"queued": true
}
}
{
"ok": 0,
"error": {
"id": "4082",
"code": 400,
"desc": "Invalid field value",
"advice": "Check extra for the field that failed validation.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4161",
"code": 429,
"desc": "A security message was sent recently",
"advice": "The member already got this message within the last hour. Treat the event as reported; extra.retry_after says when the same event can queue a message again.",
"extra": {}
}
}
Uploads
Upload card and receipt photos before attaching them to an order.
Upload images
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.
https://api.cytrongift.com/v1/uploads/imagesBody
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]"$answer = $cytron->request('POST', '/uploads/images');
print_r($answer['data']);const answer = await cytron.request('POST', '/uploads/images');
console.log(answer.data);answer = cytron.request('POST', '/uploads/images')
print(answer['data'])env, err := cytron.Request("POST", "/uploads/images", nil, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4066",
"code": 403,
"desc": "File is already attached to an order",
"advice": "Once a photo is attached to an order, it cannot be deleted through the API.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4000",
"code": 415,
"desc": "Unsupported content type",
"advice": "Use application/json, or multipart/form-data for POST /uploads/images.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4065",
"code": 409,
"desc": "Idempotency key was used for a different request",
"advice": "Use the same key only when retrying the exact same request. For a new request, use a new key.",
"extra": {}
}
}
Delete an unused upload
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.
https://api.cytrongift.com/v1/uploads/deleteBody
{
"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"}'$answer = $cytron->request('POST', '/uploads/delete', [ 'upload_id' => '941c...29f', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/uploads/delete', {"upload_id":"941c...29f"});
console.log(answer.data);answer = cytron.request('POST', '/uploads/delete', { "upload_id": "941c...29f"})
print(answer['data'])env, err := cytron.Request("POST", "/uploads/delete", map[string]any{"upload_id": "941c...29f"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"upload_id": "941c...29f",
"deleted": true
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4066",
"code": 403,
"desc": "File is already attached to an order",
"advice": "Once a photo is attached to an order, it cannot be deleted through the API.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Upload limits and pending files
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.
https://api.cytrongift.com/v1/uploads/configRequest
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"$answer = $cytron->request('GET', '/uploads/config');
print_r($answer['data']);const answer = await cytron.request('GET', '/uploads/config');
console.log(answer.data);answer = cytron.request('GET', '/uploads/config')
print(answer['data'])env, err := cytron.Request("GET", "/uploads/config", nil, false)
fmt.Println(string(env.Data)) 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
}
]
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
Preview an upload
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).
https://api.cytrongift.com/v1/uploads/previewQuery
| Name | Type | About |
|---|---|---|
upload_id * | string | The 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"$answer = $cytron->request('GET', '/uploads/preview');
print_r($answer['data']);const answer = await cytron.request('GET', '/uploads/preview');
console.log(answer.data);answer = cytron.request('GET', '/uploads/preview')
print(answer['data'])env, err := cytron.Request("GET", "/uploads/preview", nil, false)
fmt.Println(string(env.Data)) Response
A successful JSON response with an empty data field.
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4008",
"code": 403,
"desc": "Record belongs to another account",
"advice": "You can only read and update records in your own account.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Sell
Create orders to sell gift cards and game keys.
Sell gift cards
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.
https://api.cytrongift.com/v1/sell/cardsBody
{
"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}}'$answer = $cytron->request('POST', '/sell/cards', [ '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, ], ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/sell/cards', {"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}});
console.log(answer.data);answer = cytron.request('POST', '/sell/cards', { "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 }})
print(answer['data'])env, err := cytron.Request("POST", "/sell/cards", map[string]any{"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}}, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4063",
"code": 400,
"desc": "Item does not match the selected brand, platform or country",
"advice": "Check the item in the catalogue and use its brand, platform and country ids.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4086",
"code": 403,
"desc": "E-mail address is not confirmed",
"advice": "Selling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4065",
"code": 409,
"desc": "Idempotency key was used for a different request",
"advice": "Use the same key only when retrying the exact same request. For a new request, use a new key.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
Sell game keys
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.
https://api.cytrongift.com/v1/sell/gamesBody
{
"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}}'$answer = $cytron->request('POST', '/sell/games', [ '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, ], ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/sell/games', {"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}});
console.log(answer.data);answer = cytron.request('POST', '/sell/games', { "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 }})
print(answer['data'])env, err := cytron.Request("POST", "/sell/games", map[string]any{"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}}, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4086",
"code": 403,
"desc": "E-mail address is not confirmed",
"advice": "Selling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4065",
"code": 409,
"desc": "Idempotency key was used for a different request",
"advice": "Use the same key only when retrying the exact same request. For a new request, use a new key.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
Quote a sale
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.
https://api.cytrongift.com/v1/sell/quoteBody
{
"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}'$answer = $cytron->request('POST', '/sell/quote', [ 'kind' => 'cards', 'item_id' => 1, 'category_id' => 1, 'country_id' => 9, 'quantity' => 2, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/sell/quote', {"kind":"cards","item_id":1,"category_id":1,"country_id":9,"quantity":2});
console.log(answer.data);answer = cytron.request('POST', '/sell/quote', { "kind": "cards", "item_id": 1, "category_id": 1, "country_id": 9, "quantity": 2})
print(answer['data'])env, err := cytron.Request("POST", "/sell/quote", map[string]any{"kind": "cards","item_id": 1,"category_id": 1,"country_id": 9,"quantity": 2}, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4063",
"code": 400,
"desc": "Item does not match the selected brand, platform or country",
"advice": "Check the item in the catalogue and use its brand, platform and country ids.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4086",
"code": 403,
"desc": "E-mail address is not confirmed",
"advice": "Selling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4062",
"code": 404,
"desc": "Gift card or game not found",
"advice": "Choose an item currently accepted for sale from GET /catalog/cards or GET /catalog/games.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Outcome of a sale request
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_-].
https://api.cytrongift.com/v1/sell/requestsQuery
| Name | Type | About |
|---|---|---|
request_id * | string | The 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"$answer = $cytron->request('GET', '/sell/requests');
print_r($answer['data']);const answer = await cytron.request('GET', '/sell/requests');
console.log(answer.data);answer = cytron.request('GET', '/sell/requests')
print(answer['data'])env, err := cytron.Request("GET", "/sell/requests", nil, false)
fmt.Println(string(env.Data)) 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"
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4090",
"code": 409,
"desc": "This request id was cancelled",
"advice": "A lookup closed this request id before the request arrived, so nothing was created. Send the request again with a new request id.",
"extra": {}
}
}
Withdrawals
Request payouts and check their status and history.
Request a payout
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.
https://api.cytrongift.com/v1/withdrawal/createBody
{
"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"}'$answer = $cytron->request('POST', '/withdrawal/create', [ 'amount' => 10.5, 'method_id' => 2, 'wallet' => '1A1zP1...', 'fio' => 'John Doe', 'amount_type' => 0, 'request_id' => 'wd_01K1A8T4S7Q2M5N9P3R6', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/withdrawal/create', {"amount":10.5,"method_id":2,"wallet":"1A1zP1...","fio":"John Doe","amount_type":0,"request_id":"wd_01K1A8T4S7Q2M5N9P3R6"});
console.log(answer.data);answer = cytron.request('POST', '/withdrawal/create', { "amount": 10.5, "method_id": 2, "wallet": "1A1zP1...", "fio": "John Doe", "amount_type": 0, "request_id": "wd_01K1A8T4S7Q2M5N9P3R6"})
print(answer['data'])env, err := cytron.Request("POST", "/withdrawal/create", map[string]any{"amount": 10.5,"method_id": 2,"wallet": "1A1zP1...","fio": "John Doe","amount_type": 0,"request_id": "wd_01K1A8T4S7Q2M5N9P3R6"}, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4053",
"code": 400,
"desc": "Wallet format does not match the payout method",
"advice": "Check the wallet format for your chosen payout method.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4086",
"code": 403,
"desc": "E-mail address is not confirmed",
"advice": "Selling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4065",
"code": 409,
"desc": "Idempotency key was used for a different request",
"advice": "Use the same key only when retrying the exact same request. For a new request, use a new key.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4156",
"code": 429,
"desc": "Too many wrong authenticator codes",
"advice": "Two-factor authentication of this account is locked for a while after five wrong codes in fifteen minutes; even a right code is refused until then. Wait the seconds given in extra.retry_after.",
"extra": {}
}
}
Payout history
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.
https://api.cytrongift.com/v1/withdrawal/transactionsQuery
| Name | Type | About |
|---|---|---|
id | integer | Return one payout directly in data, without the list wrapper. |
type | string | main or referral |
cursor | integer | Return items with ids less than this cursor. |
limit | integer, default 20 | Items 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"$answer = $cytron->request('GET', '/withdrawal/transactions');
print_r($answer['data']);const answer = await cytron.request('GET', '/withdrawal/transactions');
console.log(answer.data);answer = cytron.request('GET', '/withdrawal/transactions')
print(answer['data'])env, err := cytron.Request("GET", "/withdrawal/transactions", nil, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"items": [],
"limit": 20,
"cursor": 0,
"next_cursor": null,
"filters": {
"type": null
}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4007",
"code": 404,
"desc": "Record not found",
"advice": "Check the id. There is no matching record in your account.",
"extra": {}
}
}
Quote a payout
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.
https://api.cytrongift.com/v1/withdrawal/quoteBody
{
"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}'$answer = $cytron->request('POST', '/withdrawal/quote', [ 'balance_source' => 'main', 'method_id' => 2, ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/withdrawal/quote', {"balance_source":"main","method_id":2});
console.log(answer.data);answer = cytron.request('POST', '/withdrawal/quote', { "balance_source": "main", "method_id": 2})
print(answer['data'])env, err := cytron.Request("POST", "/withdrawal/quote", map[string]any{"balance_source": "main","method_id": 2}, false)
fmt.Println(string(env.Data)) 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
}
}
{
"ok": 0,
"error": {
"id": "4052",
"code": 400,
"desc": "Payout method not found",
"advice": "Choose a method id from GET /catalog/payments.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4086",
"code": 403,
"desc": "E-mail address is not confirmed",
"advice": "Selling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "5008",
"code": 503,
"desc": "Service is under maintenance",
"advice": "Wait the number of seconds in Retry-After, then try again.",
"extra": {}
}
}
Outcome of a payout request
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.
https://api.cytrongift.com/v1/withdrawal/requestsQuery
| Name | Type | About |
|---|---|---|
request_id * | string | The 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"$answer = $cytron->request('GET', '/withdrawal/requests');
print_r($answer['data']);const answer = await cytron.request('GET', '/withdrawal/requests');
console.log(answer.data);answer = cytron.request('GET', '/withdrawal/requests')
print(answer['data'])env, err := cytron.Request("GET", "/withdrawal/requests", nil, false)
fmt.Println(string(env.Data)) 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
}
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "4090",
"code": 409,
"desc": "This request id was cancelled",
"advice": "A lookup closed this request id before the request arrived, so nothing was created. Send the request again with a new request id.",
"extra": {}
}
}
Support
Create support tickets you can also follow in your account.
Create a support ticket
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.
https://api.cytrongift.com/v1/support/createBody
{
"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"}'$answer = $cytron->request('POST', '/support/create', [ 'subject' => 'Question', 'message' => 'At least twenty characters of text.', 'name' => 'John Doe', 'email' => '[email protected]', 'lang' => 'en', ]);
print_r($answer['data']);const answer = await cytron.request('POST', '/support/create', {"subject":"Question","message":"At least twenty characters of text.","name":"John Doe","email":"[email protected]","lang":"en"});
console.log(answer.data);answer = cytron.request('POST', '/support/create', { "subject": "Question", "message": "At least twenty characters of text.", "name": "John Doe", "email": "[email protected]", "lang": "en"})
print(answer['data'])env, err := cytron.Request("POST", "/support/create", map[string]any{"subject": "Question","message": "At least twenty characters of text.","name": "John Doe","email": "[email protected]","lang": "en"}, false)
fmt.Println(string(env.Data)) Response
{
"ok": 1,
"data": {
"ticket_id": 1888,
"code": "b296...",
"status": 0,
"name": "John Doe",
"email": "[email protected]",
"subject": "Question",
"date": 1788605297
}
}
{
"ok": 0,
"error": {
"id": "4012",
"code": 400,
"desc": "Required field is missing",
"advice": "Check extra for the field name and include it in your request.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3003",
"code": 401,
"desc": "Signature does not match",
"advice": "Sign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3014",
"code": 403,
"desc": "Required scope is missing",
"advice": "Check extra for the scope this endpoint needs. Contact support to request access to it.",
"extra": {}
}
}
{
"ok": 0,
"error": {
"id": "3011",
"code": 429,
"desc": "Too many requests",
"advice": "Slow 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.",
"extra": {}
}
}
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);
}
}
}
// Cytrongift API client for Node 18+ (fetch and WebCrypto, no dependencies).
//
// CYTRON_API_KEY=ck_... CYTRON_API_SECRET=cs_... node client.mjs [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.
import { createHmac } from 'node:crypto';
export class CytronApi {
#base; #key; #secret; #token = '';
constructor(base, key, secret) {
this.#base = base.replace(/\/+$/, '');
this.#key = key;
this.#secret = secret;
}
// One request. The signature covers METHOD, PATH (without /v1), TIMESTAMP and the raw body.
async request(method, path, body = null, bearer = false) {
method = method.toUpperCase();
const raw = body === null ? '' : JSON.stringify(body);
const headers = { Accept: 'application/json' };
if (raw !== '') { headers['Content-Type'] = 'application/json'; }
if (bearer && this.#token) {
headers.Authorization = 'Bearer ' + this.#token;
} else {
const ts = String(Math.floor(Date.now() / 1000));
const cleanPath = '/' + new URL(path, 'https://x').pathname.replace(/^\/+/, '');
headers['X-Api-Key'] = this.#key;
headers['X-Timestamp'] = ts;
headers['X-Signature'] = createHmac('sha256', this.#secret).update(`${method}\n${cleanPath}\n${ts}\n${raw}`).digest('hex');
}
const res = await fetch(this.#base + path, { method, headers, body: raw === '' ? undefined : raw });
const data = await res.json();
if (typeof data !== 'object' || data === null) { throw new Error(`HTTP ${res.status}: not a JSON envelope`); }
return data;
}
// Exchange the signature for a Bearer token and keep it for later calls.
async auth(ttl = 3600) {
const answer = await this.request('POST', '/auth', { ttl });
if (answer.ok) { this.#token = answer.data.access_token; }
return answer;
}
}
if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
const cytron = new CytronApi(process.argv[2] || 'https://api.cytrongift.com/v1', process.env.CYTRON_API_KEY || '', process.env.CYTRON_API_SECRET || '');
const 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)],
];
for (const [name, call] of steps) {
const answer = await call();
console.log(name.padEnd(12), answer.ok ? 'ok' : `error ${answer.error?.id} ${answer.error?.desc}`);
if (!answer.ok) { process.exit(1); }
}
}
# Cytrongift API client for Python 3.8+ (standard library only, no dependencies).
#
# CYTRON_API_KEY=ck_... CYTRON_API_SECRET=cs_... python3 client.py [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.
import hashlib
import hmac
import json
import os
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
class CytronApi:
def __init__(self, base, key, secret):
self.base = base.rstrip('/')
self.key = key
self.secret = secret
self.token = ''
# One request. The signature covers METHOD, PATH (without /v1), TIMESTAMP and the raw body.
def request(self, method, path, body=None, bearer=False):
method = method.upper()
raw = '' if body is None else json.dumps(body, separators=(',', ':'))
headers = {'Accept': 'application/json'}
if raw != '':
headers['Content-Type'] = 'application/json'
if bearer and self.token:
headers['Authorization'] = 'Bearer ' + self.token
else:
ts = str(int(time.time()))
clean_path = '/' + urllib.parse.urlsplit(path).path.lstrip('/')
message = '\n'.join([method, clean_path, ts, raw]).encode()
headers['X-Api-Key'] = self.key
headers['X-Timestamp'] = ts
headers['X-Signature'] = hmac.new(self.secret.encode(), message, hashlib.sha256).hexdigest()
req = urllib.request.Request(self.base + path, data=raw.encode() if raw else None, headers=headers, method=method)
try:
with urllib.request.urlopen(req, timeout=30) as res:
text = res.read().decode()
except urllib.error.HTTPError as err:
# the API answers its envelope on every status, so the body is the answer
text = err.read().decode()
answer = json.loads(text)
if not isinstance(answer, dict):
raise RuntimeError('not a JSON envelope')
return answer
# Exchange the signature for a Bearer token and keep it for later calls.
def auth(self, ttl=3600):
answer = self.request('POST', '/auth', {'ttl': ttl})
if answer.get('ok'):
self.token = answer['data']['access_token']
return answer
if __name__ == '__main__':
cytron = CytronApi(sys.argv[1] if len(sys.argv) > 1 else 'https://api.cytrongift.com/v1', os.environ.get('CYTRON_API_KEY', ''), os.environ.get('CYTRON_API_SECRET', ''))
steps = [
('health', lambda: cytron.request('GET', '/health')),
('config', lambda: cytron.request('GET', '/config')),
('stats', lambda: cytron.request('GET', '/stats')),
('offers', lambda: cytron.request('GET', '/catalog/offers?limit=5')),
('balance', lambda: cytron.request('GET', '/account/balance')),
('auth', lambda: cytron.auth()),
('balance_jwt', lambda: cytron.request('GET', '/account/balance', None, True)),
]
for name, call in steps:
answer = call()
error = answer.get('error') or {}
print(name.ljust(12), 'ok' if answer.get('ok') else 'error %s %s' % (error.get('id'), error.get('desc')))
if not answer.get('ok'):
sys.exit(1)
// Cytrongift API client in Go (standard library only).
//
// CYTRON_API_KEY=ck_... CYTRON_API_SECRET=cs_... go run . [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.
package main
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
// Envelope is the answer of every endpoint.
type Envelope struct {
OK int `json:"ok"`
Data json.RawMessage `json:"data"`
Error *struct {
ID string `json:"id"`
Code int `json:"code"`
Desc string `json:"desc"`
} `json:"error"`
}
// CytronApi signs requests with an application key.
type CytronApi struct {
Base string
Key string
Secret string
token string
http *http.Client
}
// NewCytronApi returns a client for the base address, for example https://api.cytrongift.com/v1.
func NewCytronApi(base, key, secret string) *CytronApi {
return &CytronApi{Base: strings.TrimRight(base, "/"), Key: key, Secret: secret, http: &http.Client{Timeout: 30 * time.Second}}
}
// Request sends one call. The signature covers METHOD, PATH (without /v1), TIMESTAMP and the raw body.
func (c *CytronApi) Request(method, path string, body any, bearer bool) (*Envelope, error) {
method = strings.ToUpper(method)
raw := []byte{}
if body != nil {
var err error
if raw, err = json.Marshal(body); err != nil {
return nil, err
}
}
req, err := http.NewRequest(method, c.Base+path, bytes.NewReader(raw))
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
if len(raw) > 0 {
req.Header.Set("Content-Type", "application/json")
}
if bearer && c.token != "" {
req.Header.Set("Authorization", "Bearer "+c.token)
} else {
u, _ := url.Parse(path)
ts := strconv.FormatInt(time.Now().Unix(), 10)
mac := hmac.New(sha256.New, []byte(c.Secret))
mac.Write([]byte(method + "\n/" + strings.TrimLeft(u.Path, "/") + "\n" + ts + "\n" + string(raw)))
req.Header.Set("X-Api-Key", c.Key)
req.Header.Set("X-Timestamp", ts)
req.Header.Set("X-Signature", hex.EncodeToString(mac.Sum(nil)))
}
res, err := c.http.Do(req)
if err != nil {
return nil, err
}
defer res.Body.Close()
answer, err := io.ReadAll(res.Body)
if err != nil {
return nil, err
}
var env Envelope
if err := json.Unmarshal(answer, &env); err != nil {
return nil, fmt.Errorf("HTTP %d: not a JSON envelope", res.StatusCode)
}
return &env, nil
}
// Auth exchanges the signature for a Bearer token and keeps it for later calls.
func (c *CytronApi) Auth(ttl int) (*Envelope, error) {
env, err := c.Request("POST", "/auth", map[string]int{"ttl": ttl}, false)
if err == nil && env.OK == 1 {
var data struct {
AccessToken string `json:"access_token"`
}
if err := json.Unmarshal(env.Data, &data); err == nil {
c.token = data.AccessToken
}
}
return env, err
}
func main() {
base := "https://api.cytrongift.com/v1"
if len(os.Args) > 1 {
base = os.Args[1]
}
cytron := NewCytronApi(base, os.Getenv("CYTRON_API_KEY"), os.Getenv("CYTRON_API_SECRET"))
steps := []struct {
name string
call func() (*Envelope, error)
}{
{"health", func() (*Envelope, error) { return cytron.Request("GET", "/health", nil, false) }},
{"config", func() (*Envelope, error) { return cytron.Request("GET", "/config", nil, false) }},
{"stats", func() (*Envelope, error) { return cytron.Request("GET", "/stats", nil, false) }},
{"offers", func() (*Envelope, error) { return cytron.Request("GET", "/catalog/offers?limit=5", nil, false) }},
{"balance", func() (*Envelope, error) { return cytron.Request("GET", "/account/balance", nil, false) }},
{"auth", func() (*Envelope, error) { return cytron.Auth(3600) }},
{"balance_jwt", func() (*Envelope, error) { return cytron.Request("GET", "/account/balance", nil, true) }},
}
for _, step := range steps {
env, err := step.call()
if err != nil {
fmt.Printf("%-12s %v\n", step.name, err)
os.Exit(1)
}
if env.OK != 1 {
fmt.Printf("%-12s error %s %s\n", step.name, env.Error.ID, env.Error.Desc)
os.Exit(1)
}
fmt.Printf("%-12s ok\n", step.name)
}
}
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.
3xxx · Authentication and limits
| id | HTTP | Meaning / what to do |
|---|---|---|
| 3000 | 405 | HTTP method not supportedCheck which HTTP methods this endpoint accepts. |
| 3001 | 401 | Authentication requiredSend X-Api-Key, X-Timestamp and X-Signature, or a bearer token in the Authorization header. |
| 3002 | 401 | Request timestamp is out of rangeSend X-Timestamp as Unix time in seconds, within 300 seconds of the server clock. |
| 3003 | 401 | Signature does not matchSign METHOD, PATH, TIMESTAMP and the exact request body with your API secret. Separate each part with a newline. |
| 3004 | 403 | API access is disabled for this accountContact support to enable API access. |
| 3005 | 403 | Account is blockedContact support to review the block. |
| 3006 | 401 | API key not foundCheck that X-Api-Key matches the key issued in your account settings. |
| 3007 | 401 | Bearer token is missing or malformedSend the token in this format: Authorization: Bearer {jwt}. |
| 3008 | 401 | Token has expiredRequest a new token from POST /auth using your HMAC headers. |
| 3009 | 401 | Invalid tokenThe token signature or payload is invalid. Request a new token from POST /auth. |
| 3010 | 503 | Token signing key is not configuredWe cannot issue or verify tokens right now. Contact support. |
| 3011 | 429 | Too 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. |
| 3012 | 403 | Application key is inactiveThe key was revoked or expired 24 hours after rotation. Create or rotate a key in Apps & API in your account. |
| 3013 | 403 | Application access is disabledThe application is paused by our team, disabled by its owner or awaiting approval. Check extra for the reason. |
| 3014 | 403 | Required scope is missingCheck extra for the scope this endpoint needs. Contact support to request access to it. |
| 3015 | 503 | Key store is not configuredWe cannot read application keys right now. Contact support. |
| 3016 | 401 | Key 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
| id | HTTP | Meaning / what to do |
|---|---|---|
| 4000 | 415 | Unsupported content typeUse application/json, or multipart/form-data for POST /uploads/images. |
| 4007 | 404 | Record not foundCheck the id. There is no matching record in your account. |
| 4008 | 403 | Record belongs to another accountYou can only read and update records in your own account. |
| 4010 | 403 | No account linked to these credentialsYour credentials are valid, but they are not linked to an account. Contact support. |
| 4012 | 400 | Required field is missingCheck extra for the field name and include it in your request. |
| 4013 | 400 | Invalid JSON bodyCheck the request body. It must be a valid JSON object. |
| 4017 | 400 | Invalid amountUse a number greater than zero, with no more than 2 decimal places. |
| 4019 | 404 | User not foundCheck the id. No user matches it. |
| 4052 | 400 | Payout method not foundChoose a method id from GET /catalog/payments. |
| 4053 | 400 | Wallet format does not match the payout methodCheck the wallet format for your chosen payout method. |
| 4054 | 400 | Insufficient fundsThe requested payout is greater than your balance. Reduce the amount and try again. |
| 4059 | 400 | Invalid email addressCheck the address format, for example [email protected]. |
| 4060 | 400 | Invalid ticket subjectUse 3 to 64 characters for the subject. |
| 4061 | 400 | Invalid ticket messageUse 20 to 8192 characters for the message. |
| 4062 | 404 | Gift card or game not foundChoose an item currently accepted for sale from GET /catalog/cards or GET /catalog/games. |
| 4063 | 400 | Item does not match the selected brand, platform or countryCheck the item in the catalogue and use its brand, platform and country ids. |
| 4064 | 400 | Card details are missingSend codes in `cards`, or upload card photos first and pass their card_upload_ids. |
| 4065 | 409 | Idempotency 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. |
| 4066 | 403 | File is already attached to an orderOnce a photo is attached to an order, it cannot be deleted through the API. |
| 4067 | 429 | Too many orders in the last hourWait before trying again. Send one order at a time, with a short pause between requests. |
| 4068 | 409 | Code 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. |
| 4073 | 400 | No file receivedSend images in files[] using multipart/form-data. |
| 4074 | 400 | Unsupported image formatTry a JPEG, PNG or WebP image. |
| 4075 | 400 | File is too largeCheck extra for the size limit in bytes and upload a smaller file. |
| 4076 | 500 | Could not save the fileTry uploading it again, or choose another file. |
| 4082 | 400 | Invalid field valueCheck extra for the field that failed validation. |
| 4084 | 409 | Could 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. |
| 4085 | 400 | Webhook limit reachedDelete a webhook you no longer use before adding another. Check extra for the limit. |
| 4086 | 403 | E-mail address is not confirmedSelling and payouts need a confirmed address. Add one with POST /account/email and open the link in the mail. |
| 4087 | 409 | E-mail address belongs to another accountUse another address, or sign in on the website with the account that holds this one and link it. |
| 4088 | 429 | Verification 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. |
| 4090 | 409 | This 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. |
| 4091 | 409 | Another request of this account is in progressWait for the running request to finish, then retry with the same request id. |
5xxx · Transport and platform
| id | HTTP | Meaning / what to do |
|---|---|---|
| 5003 | 503 | Endpoint is temporarily disabledTry again later. |
| 5004 | 400 | Invalid endpoint pathCheck the path for characters the router does not accept. |
| 5005 | 404 | Endpoint not foundCheck the path in the API documentation. |
| 5007 | 500 | Something went wrong on our endWe could not complete the request. Try again later. |
| 5008 | 503 | Service 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
POST /account/notifications/event(scopenotifications:manage, a user token only) lets a first-party application report a security event of the member:{"event": "pin_reset"}after its own app PIN was removed by a reset. The core queues one Telegram message to the member and answersqueued(falsewhen the member's notifications are off). Nothing of the PIN is sent.- The same event within an hour answers
429with error4161(notice_wait),retry_afterand aRetry-Afterheader, so the call cannot flood the member. - New error
4161(security message sent recently).
v1.5.3 12 Nov 2026
POST /account/2fa/verifychecks a live authenticator code of the user behind a user token and changes nothing else: a right code is spent, a wrong one counts against the shared lock (4151,4156). An account with two-factor authentication off answers409with error4157(totp_off).POST /account/email/codemails a six-digit one-time code to the confirmed address for apurpose(pin_resetfor now) and answers the masked address,expires_in(900) andretry_after; a new mail voids the earlier code. One mail a minute and three an hour per account:429with error4158(code_wait) andretry_after.POST /account/email/code/confirmspends a right code once and answersverified: true; a wrong one answers400with error4159(code_invalid) andattempts_left, the fifth wrong try voids it, and without a live code it answers409with error4160(code_missing).- The three endpoints answer only a user token (
Bearer ut_...) and needprofile:write. - New errors
4157(two-factor is off),4158(code mail sent recently),4159(wrong code) and4160(no live code).
v1.5.2 11 Nov 2026
- Card and game logos stay available through
GET /catalog/imagesafter the item leaves the sale, so order history and latest sales keep their pictures.
v1.5.1 11 Nov 2026
GET /statscounts its figures from the database instead of the typed website settings, refreshed at most once an hour:card_types(live catalogue items a seller can choose now),members(confirmed accounts),items_sold(items in completed orders) and the newreferral_rewards(lifetime referral credits paid to members, a number in USD with two decimals).earnedis removed fromGET /stats; the API publishes no total of money paid to sellers.GET /tma/home/statisticsfollows the same change and returnsreferral_rewardsas a two-decimal USD string.
v1.5.0 11 Nov 2026
POST /auth/identity/claim/confirmtakestotp: when the account that would hold the identity has two-factor authentication on, a proven code or token alone answers403with error4150(totp_required), the claim stays live and nothing is counted; the same proof sent again withtotpfinishes the sign-in. A wrongtotpanswers4151(totp_invalid) and counts as one wrong attempt.POST /withdrawal/createtakestotp: a user signed in with a user token (Bearer ut_...) whose account has two-factor authentication on confirms every payout with it (4150without,4151on a wrong one). Requests signed with an application key and their JWTs are not asked.GET /account/2fa,POST /account/2fa/setup,POST /account/2fa/enableandPOST /account/2fa/disablemanage the two-factor authentication of the user behind a user token; it is the same switch and the same key as on the website.POST /account/password/setupmails the link that sets the first website password of an account created in an application;GET /account/profileaddstwo_factor.- Five wrong authenticator codes of one account within 15 minutes, wherever they were sent (the website included), lock its second factor until that window ends: every call that asks for a code then answers
429with error4156(totp_locked),retry_afterand aRetry-Afterheader, even for a right code. - New errors
4150(authenticator code needed),4151(wrong authenticator code),4152(two-factor already on),4153(no setup waiting),4154(the account already has a password),4155(password mail sent recently) and4156(two-factor locked after wrong codes).
v1.4.0 10 Nov 2026
POST /auth/identity/claimmails a six-digit sign-in code to an address for a verified identity, the same answer and mail whoever holds the address;POST /auth/identity/claim/confirmtakes the code or the token of the mail's Telegram button and answers the token pair withoutcome(created,linked,updated) and the confirmedemail.POST /auth/identitytakescreate(defaulttrue): withfalsean unknown identity answers404with error4146and nothing is created. It also takesclient_ip, the visitor's address, for the sign-up limit.- New errors
4146(no account for the identity yet),4147(too many wrong sign-in codes),4148(wrong sign-in code) and4149(no live sign-in code).
v1.3.0 6 Nov 2026
POST /auth/identitytakesstart_param, the Telegram launch parameter:ref_<id>, a legacy id or a referral code names the inviter of a new account; the answer addsuser.emailanduser.email_verified.GET /account/profilereturns the acting user's name, handle, picture, mailbox state, referral code, language, bonus level and registration time.POST /account/emailadds an address to an unconfirmed account and mails the verification link;POST /account/email/resendmails it again. One mail a minute and five an hour per account, error4088withretry_after; an address another account holds answers4087.POST /sell/cards,POST /sell/gamesandPOST /withdrawal/createneed a confirmed address: an account withemail_verifiedfalse answers403with error4086.- A request with a user token (
Bearer ut_...) counts against its own limit of 60 a minute and against the application's limit; theX-RateLimit-*headers report whichever has fewer requests left. A first-party application may hold up to 6000 requests a minute. - New scopes
identity:linkandnotifications:manage, for first-party applications only; a user token keeps them. GET /config:links.newsreturns next tolinks.blogwith the same value for one release.- Added GET /stats and GET /sales/latest, public site counters and the latest anonymous sales, without credentials.
- Added GET /catalog/offers, the priced list of accepted gift cards with search and paging, and GET /catalog/images, which streams brand, platform, card, game, country and payment images.
POST /sell/quoteandPOST /withdrawal/quoteprice a sale or a whole-balance payout for your account without creating anything.POST /sell/cardsandPOST /sell/gamesacceptrequest_id(orIdempotency-Key) andexpected_quote: a retry returns the stored order withduplicate: true, a moved price answersstatus: "price_changed"with the fresh quote;GET /sell/requestsreports the outcome of an id and cancels an unseen one (a late create then gets4090).POST /withdrawal/createacceptsbalance_sourcefor the whole balance of one source andexpected_quote; arequest_idof 32 characters or more gets a receipt thatGET /withdrawal/requestsreads.GET /uploads/configlists the upload limits and your pending uploads,GET /uploads/previewreturns one as WebP, andPOST /uploads/imagesaccepts your ownupload_idso a retried upload is stored once.GET /account/historyandGET /account/history/itemgive orders and payouts in one paged feed with full details;GET /account/summarythe lifetime earnings;GET /account/referralsandGET /account/referrals/historythe referral programme with your invite links.- Error
4091: another request of the same account holds the lock for more than five seconds; retry with the same id. GETandPATCH /account/notifications(scopenotifications:manage): the Telegram notification switch of the user with a revision; a stale revision returns4141.- Account link over the public API:
POST /identities/link/start(scopeidentity:link),status,cancel,assessment, andcomplete, which answers like/auth/identityfor the site account; the site page approves throughPOST /identities/link/website. - A Telegram account with history merges into the site account by itself only when the assessment is clean and at most 100 USD moves; otherwise
completereturns4142and the link waits for an operator. - New errors
4142(manual review),4143(link request expired),4144(no Telegram identity) and4145(account busy). - User tokens from
/auth/identitynow carry every scope of the application exceptidentity:assert, soidentity:linkandnotifications:managereach the user's token.
v1.2.1 30 Oct 2026
GET /catalog/country2datais nowGET /catalog/countries; the old path answers404with error5005.GET /config: thelinks.newsentry is nowlinks.blog.- The Sandbox chapter of the guide is a step-by-step walkthrough; the documentation page links every Apps & API mention to the account page.
Cytrongift API v1.5.4. OpenAPI specification: openapi.json.Powered by Perfecto Web