Rewards

💰 Rewards API

Query iNFT holder rewards and distribution events.

Features:

• Lifetime TWN earnings per twin

• Monthly and 30-day summaries

• Detailed reward event history

• Category-based breakdowns

Get rewards summary

get

Retrieve a comprehensive rewards summary for a specific twin, including lifetime earnings, monthly totals, and category breakdowns.

Includes:

• Lifetime TWN earnings

• Month-to-date (MTD) rewards

• Last 30 days rewards

• Breakdown by reward category

Path parameters

short_idstringRequired

Short twin ID (e.g., G0). Full form (e.g., TWN-G0) is also accepted.

Query parameters

period_ymstringOptional

Optional period in YYYYMM format; defaults to current UTC month

Example: 202501

Responses

200

OK

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/twins/{short_id}/rewards

cURLfetch

curl -s "https://api.twnlabs.com/v1/twins/G0/rewards?period_ym=202501"

{
  "success": true,
  "rewards": {
    "twin_id": "TWN-G0",
    "period_ym": "202501",
    "lifetime_twn": "1250.500000",
    "mtd_twn": "45.250000",
    "last30d_twn": "78.125000",
    "by_category": [
      {
        "code": "text",
        "amount": "text"
      }
    ],
    "last_airdrop": {
      "period_ym": "text",
      "amount": "text"
    },
    "mint_detected": true
  }
}

List reward events

get

Retrieve a detailed history of reward distribution events for a specific twin.

Query Options:

• Filter by period (YYYYMM format)

• Get all historical events with period=all

• Paginate with limit parameter

Path parameters

short_idstringRequired

Short twin ID (e.g., G0). Full form (e.g., TWN-G0) is also accepted.

Query parameters

period_ymstringOptional

Filter by period in YYYYMM format

Example: 202501

limitinteger · min: 1 · max: 200Optional

Maximum number of events to return (max 200)

Example: 50

periodstring · enumOptional

Set to "all" to return events across all periods (honors server max limit)

Example: allPossible values:

Responses

200

OK

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/twins/{short_id}/rewards/events

HTTPcURLJavaScriptPython

GET /v1/twins/{short_id}/rewards/events HTTP/1.1
Host: api.twnlabs.com
Accept: */*

{
  "success": true,
  "events": [
    {
      "block_time": "text",
      "period_ym": "text",
      "category_code": "text",
      "category_name": "text",
      "amount": "text",
      "usd_amount": "text",
      "tx_signature": "text",
      "network": "text",
      "status": "text",
      "token_symbol": "text"
    }
  ]
}