GithubSupport

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
get
/twins/{short_id}/rewards
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
get
/twins/{short_id}/rewards/events
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"
    }
  ]
}
PreviousDownloadsNextTwins

Last updated