API Documentation

REST API for working with gift collections

To use the API, you need to create an application and include the app_token in your requests.

Applications that do not use the app_token and make excessive requests may have their IP address blocked.

Get app_token

API access may be restricted or blocked without warning for abuse.

Create Application

Base URL

https://poso.see.tg

Protocol

HTTPS (SSL/TLS)

Format

JSON

Caching

Redis (5 min)

Authorization

Some endpoints require authorization via Telegram Web App. The tgauth parameter is a JSON string with Telegram authorization data.

{ "id": 123456789, "first_name": "John", "username": "johndoe", "auth_date": 1702300000, "hash": "..." }

Endpoints

GET/health

Server health check

Response:

{ "status": "ok" }

POST/api/login

Telegram authorization validation

Body:

{ "id": 123456789, "first_name": "John", "username": "johndoe", "auth_date": 1702300000, "hash": "..." }

Response:

{ "success": true }

Gifts

GET/api/gifts

Returns a list of gifts with filtering, sorting and pagination support

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
id	string	Record ID
gift_id	string	Gift ID
title	string	Title
slug	string	Slug
num	integer	Number
model_name	string	Model name
pattern_name	string	Pattern name
backdrop_name	string	Backdrop name
current_owner_id	string	Owner ID ⚠️ Requires auth
url	string	Telegram URL
market_only	bool	Only gifts for sale
limit	integer	Number of records (1-50, default: 50)
offset	integer	Offset from start
sort_by	string	num, title, updated_at
order	string	asc, desc

💡 All filters support multiple comma-separated values! Example: num=1,2,3

Response:

{ "gifts": [ { "id": "5839192838469846469", "gift_id": "5843762284240831056", "title": "Ion Gem", "slug": "IonGem", "num": 1, "model_name": "Girl Power", "model_rarity_permille": 15, "pattern_name": "Top Hat", "pattern_rarity_permille": 5, "backdrop_name": "Shamrock Green", "backdrop_rarity_permille": 20, "current_owner_id": "8d39a255-...", "url": "https://t.me/nft/IonGem-1", "updated_at": "2025-12-11T19:49:31Z", "current_owner": { ... } } ], "total": 1, "limit": 50, "offset": 0 }

History

GET/api/historyRequires auth

Returns gift transfer history between owners

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
tgauth*	string	Telegram authorization (required)
gift_id	string	Filter by gift ID
owner_id	string	Filter by new owner ID
prev_owner_id	string	Filter by previous owner ID
limit	integer	Number of records (1-5, default: 5)
offset	integer	Offset from start
sort_by	string	seen_at
order	string	asc, desc

💡 If owner_id and prev_owner_id are the same — searches where user was either sender or receiver (OR)

Response:

{ "history": [ { "seen_at": "2025-12-11T07:34:06Z", "action": "transfer", // transfer, hide, unhide "gift": { ... }, "owner": { ... }, "prev_owner": { ... } } ], "total": 1, "limit": 5, "offset": 0 }

Owners

GET/api/ownersRequires auth

Owner search with full-text search support

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
tgauth*	string	Telegram authorization (required)
id	string	Filter by ID
owner_type	string	object, hidden, blockchain
telegram_type	string	user, channel
telegram_id	string	Telegram ID
username	string	Username
name	string	Name
owner_address	string	TON address
search_query	string	Universal search by name, username, telegram_id, address
limit	integer	Number of records (1-10, default: 10)
offset	integer	Offset from start
sort_by	string	gifts_count, name, username
order	string	asc, desc

Response:

{ "owners": [ { "id": "b7c1d808-...", "owner_type": "object", "telegram_type": "user", "telegram_id": 7308887716, "username": "durov", "name": "Pavel Durov", "owner_address": "", "updated_at": "2025-12-11T19:55:48Z", "gifts_count": 1354 } ], "total": 5000, "limit": 10, "offset": 0 }

GET/api/owner

Get a single owner by filters. No authorization required

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
id	string	Filter by ID
telegram_id	string	Telegram ID
username	string	Username
owner_address	string	TON address

Response:

{ "id": "b7c1d808-...", "owner_type": "object", "telegram_type": "user", "telegram_id": 7308887716, "username": "durov", "name": "Pavel Durov", "owner_address": "", "updated_at": "2025-12-11T19:55:48Z", "gifts_count": 1354 }

Stats

GET/api/stats

Returns platform statistics

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)

Response:

{ "total_gifts": 9181102, "unique_owners": 2412314, "owners_object": 1987260, "owners_hidden": 344123, "owners_blockchain": 104104, "transfers_total": 183947, "transfers_24h": 183947, "transfers_1h": 16335, "transfers_15m": 4104, "on_market_stars": 346128, "on_market_ton": 196050, "updated_at": "2025-12-11T20:00:17.571Z" }

Errors

Error format:

{ "error": "Error description" }

200

Success

400

Validation error

401

Unauthorized

500

Server error

Back

API Documentation

REST API for working with gift collections

To use the API, you need to create an application and include the app_token in your requests.

Applications that do not use the app_token and make excessive requests may have their IP address blocked.

Get app_token

API access may be restricted or blocked without warning for abuse.

Create Application

Base URL

https://poso.see.tg

Protocol

HTTPS (SSL/TLS)

Format

JSON

Caching

Redis (5 min)

Authorization

Some endpoints require authorization via Telegram Web App. The tgauth parameter is a JSON string with Telegram authorization data.

{ "id": 123456789, "first_name": "John", "username": "johndoe", "auth_date": 1702300000, "hash": "..." }

Endpoints

GET/health

Server health check

Response:

{ "status": "ok" }

POST/api/login

Telegram authorization validation

Body:

{ "id": 123456789, "first_name": "John", "username": "johndoe", "auth_date": 1702300000, "hash": "..." }

Response:

{ "success": true }

Gifts

GET/api/gifts

Returns a list of gifts with filtering, sorting and pagination support

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
id	string	Record ID
gift_id	string	Gift ID
title	string	Title
slug	string	Slug
num	integer	Number
model_name	string	Model name
pattern_name	string	Pattern name
backdrop_name	string	Backdrop name
current_owner_id	string	Owner ID ⚠️ Requires auth
url	string	Telegram URL
market_only	bool	Only gifts for sale
limit	integer	Number of records (1-50, default: 50)
offset	integer	Offset from start
sort_by	string	num, title, updated_at
order	string	asc, desc

💡 All filters support multiple comma-separated values! Example: num=1,2,3

Response:

History

GET/api/historyRequires auth

Returns gift transfer history between owners

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
tgauth*	string	Telegram authorization (required)
gift_id	string	Filter by gift ID
owner_id	string	Filter by new owner ID
prev_owner_id	string	Filter by previous owner ID
limit	integer	Number of records (1-5, default: 5)
offset	integer	Offset from start
sort_by	string	seen_at
order	string	asc, desc

💡 If owner_id and prev_owner_id are the same — searches where user was either sender or receiver (OR)

Response:

{ "history": [ { "seen_at": "2025-12-11T07:34:06Z", "action": "transfer", // transfer, hide, unhide "gift": { ... }, "owner": { ... }, "prev_owner": { ... } } ], "total": 1, "limit": 5, "offset": 0 }

Owners

GET/api/ownersRequires auth

Owner search with full-text search support

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
tgauth*	string	Telegram authorization (required)
id	string	Filter by ID
owner_type	string	object, hidden, blockchain
telegram_type	string	user, channel
telegram_id	string	Telegram ID
username	string	Username
name	string	Name
owner_address	string	TON address
search_query	string	Universal search by name, username, telegram_id, address
limit	integer	Number of records (1-10, default: 10)
offset	integer	Offset from start
sort_by	string	gifts_count, name, username
order	string	asc, desc

Response:

GET/api/owner

Get a single owner by filters. No authorization required

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)
id	string	Filter by ID
telegram_id	string	Telegram ID
username	string	Username
owner_address	string	TON address

Response:

Stats

GET/api/stats

Returns platform statistics

Query parameters:

Parameter	Type	Description
app_token*	string	Application token (required)

Response:

Errors

Error format:

{ "error": "Error description" }

200

Success

400

Validation error

401

Unauthorized

500

Server error