Seasons & Game Mechanics API

Access season information, blockchain-based randomness, dragon spells, and genome registry.

Seasons

Get Current Season {#get-current-season}

Retrieve the current active season.

Endpoint

GET /api/v1/seasons/current

Authentication

Not required (public endpoint)

Response

{
  "id": 1,
  "created": 1699999999,
  "modified": 1699999999,
  "seasonStart": 1699999999,
  "spawnCycleEnd": 1704067199,
  "seasonEnd": 1706659199,
  "isSpawnCycleActive": true,
  "spawnAge": 30,
  "spawnSeason": "PRIMORDIAL",
  "endHash": "abc123...",
  "eggSupply": 10000,
  "spawnFee": "50.00"
}

Notes

• Returns Season 1 (PRIMORDIAL) if no seasons have started
• Includes timing, egg supply, and pricing information

List All Seasons {#list-seasons}

Get paginated list of all seasons.

Endpoint

GET /api/v1/seasons

Authentication

Not required (public endpoint)

Query Parameters

Response

[
  {
    "id": 1,
    "created": 1699999999,
    "seasonStart": 1699999999,
    "spawnCycleEnd": 1704067199,
    "seasonEnd": 1706659199,
    "isSpawnCycleActive": true,
    "spawnAge": 30,
    "spawnSeason": "PRIMORDIAL",
    "eggSupply": 10000,
    "spawnFee": "50.00"
  }
]

Get Next Season Estimate {#season-estimate}

Get estimated supply and pricing for next season.

Endpoint

GET /api/v1/seasons/estimate

Authentication

Not required (public endpoint)

Response

{
  "season": "SPRING",
  "estimatedSupply": 12000,
  "estimatedFee": "55.00"
}

Notes

• Returns PRIMORDIAL data if no seasons started
• Estimates based on current season performance

Forge (Provable Randomness)

The Forge provides provably fair randomness using blockchain entropy sources.

Get Raw Entropy {#get-entropy}

Get raw cryptographic entropy from blockchain sources.

Endpoint

GET /api/v1/forge/entropy/raw

Authentication

Not required (public endpoint)

Query Parameters

Response

{
  "entropy": "hex_string",
  "sources": {
    "btc": { /* Bitcoin block data */ },
    "eth": { /* Ethereum block data */ },
    "drak": { /* Dragonchain block data */ }
  }
}

Notes

• At least one entropy source required
• Returns raw entropy with proof of sources

Weighted Random Selection {#weighted-select}

Perform weighted random selection using blockchain entropy.

Endpoint

POST /api/v1/forge/entropy/weighted-select

Authentication

Not required (public endpoint)

Request Body

{
  "weightedItems": [
    {
      "item": "option1",
      "weight": 50
    },
    {
      "item": "option2",
      "weight": 30
    },
    {
      "item": "option3",
      "weight": 20
    }
  ],
  "btc": true,
  "eth": true,
  "drak": true,
  "nonce": "custom_nonce"
}

Response

{
  "selectedItem": "option1",
  "proof": {
    "entropy": "hex_string",
    "sources": { /* blockchain sources */ }
  }
}

Notes

• If no entropy sources specified, defaults to all three
• Higher weight = more likely selection

Matchmaker {#matchmaker}

Create randomized groups using blockchain entropy.

Endpoint

POST /api/v1/forge/entropy/matchmaker

Authentication

Not required (public endpoint)

Request Body

{
  "accounts": [
    "user1",
    "user2",
    "user3",
    "user4",
    "user5"
  ],
  "sticky": [
    [
      "user1",
      "user2"
    ]
  ],
  "maxGroupSize": 3,
  "btc": true,
  "eth": true,
  "drak": true,
  "nonce": "custom_nonce"
}

Request Fields

Response

{
  "groups": [
    ["user1", "user2"],
    ["user3", "user4"],
    ["user5"]
  ],
  "proof": {
    "entropy": "hex_string",
    "sources": { /* blockchain sources */ }
  }
}

Spells

Get Charm of Making {#get-charm-of-making}

Get public Charm of Making spell for a dragon.

Endpoint

GET /api/v1/spells/com/{assetId}

Authentication

Not required (public endpoint)

Path Parameters

Response

{
  "spell": "spell_string_here"
}

Notes

• Only works for dragon assets
• Uses dragon's CharmOfMaking, house, and magic elements

Get Binding Spell {#get-binding-spell}

Get personalized binding spell for owned dragon.

Endpoint

GET /api/v1/spells/bind/{assetId}

Authentication

Required - Must own the dragon

Path Parameters

Response

{
  "bindingSpell": "binding_spell_string"
}

Notes

• Only for owned dragons in HATCHED state
• Personalized to owner's account ID
• Different from public Charm of Making

Genomes

Register Genome {#register-genome}

Register a new genome in the genome registry.

Endpoint

PUT /api/v1/genomes/register

Authentication

Not required (public endpoint)

Request Body

{
  "genome": {
    /* Gene structure */
  }
}

Response

{
  "registeredGenomeId": "genome_id_123"
}

Notes

• Currently a placeholder implementation
• Validation logic pending

Get Registered Genome {#get-genome}

Retrieve genome by ID.

Endpoint

GET /api/v1/genomes/{id}

Authentication

Not required (public endpoint)

Path Parameters

Response

Returns RegisteredGenome model details