API Documentation

REST API for working with gift collections

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

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
`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
`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
`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
`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

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

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

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
`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
`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
`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
`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

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