Eggs & Spawning

Purchase dragon eggs and gateway keys

Eggs & Spawning API

Purchase dragon eggs, gateway keys, and gateway key vouchers during active spawn cycles.

Get Available Eggs {#get-available}

Retrieve current availability and pricing for eggs and keys.

Endpoint

GET /api/v1/eggs/available

Authentication

Required

Response

{
  "gatewayKeyVouchers": 5,
  "keys": {
    "count": 100,
    "fee": "50.00"
  },
  "eggs": {
    "count": 250,
    "fee": "100.00"
  },
  "gatewayKeyIds": [],
  "eggTransactionLimit": 10,
  "keyTransactionLimit": 5,
  "cryptoSource": "ETH",
  "conversion": {
    "ETH": "0.000025",
    "BTC": "0.0000015"
  },
  "cryptoPaymentAddress": "0x...",
  "isSpawnCycleActive": true
}

Response Fields

Field	Type	Description
`gatewayKeyVouchers`	integer	Available gateway key vouchers
`keys.count`	integer	Available keys
`keys.fee`	string	Price per key
`eggs.count`	integer	Available eggs
`eggs.fee`	string	Price per egg
`eggTransactionLimit`	integer	Max eggs per transaction
`keyTransactionLimit`	integer	Max keys per transaction
`isSpawnCycleActive`	boolean	Whether spawn cycle is active

Lock Eggs for Purchase {#lock-eggs}

Create a time-limited purchase request for eggs and keys.

Endpoint

POST /api/v1/eggs/spawn/lock

Authentication

Required

Request Body

{
  "eggs": {
    "count": 2,
    "fee": "100.00"
  },
  "keys": {
    "count": 1,
    "fee": "50.00"
  },
  "gatewayKeyVouchers": 2,
  "gatewayKeyIds": [
    101,
    102
  ],
  "cryptoSource": "ETH"
}

Request Fields

Field	Type	Required	Description
`eggs`	object	No	Eggs to purchase
`eggs.count`	integer	If eggs	Number of eggs
`eggs.fee`	string	If eggs	Price per egg (must match current)
`keys`	object	No	Keys to purchase
`keys.count`	integer	If keys	Number of keys
`keys.fee`	string	If keys	Price per key (must match current)
`gatewayKeyVouchers`	integer	No	Gateway key vouchers (must equal egg count)
`gatewayKeyIds`	integer[]	If vouchers	Gateway key IDs (no duplicates)
`cryptoSource`	string	No	Crypto to use (ETH, BTC, etc.)

Response

{
  "id": 12345,
  "accId": "user-account-id",
  "timestamp": 1700000000,
  "expires": 1700003600,
  "totalFee": "250.00",
  "web3TotalFee": "0.00625",
  "items": {
    "eggs": {
      "count": 2,
      "fee": "100.00"
    },
    "keys": {
      "count": 1,
      "fee": "50.00"
    },
    "gatewayKeyVouchers": 2,
    "gatewayKeyIds": [
      101,
      102
    ],
    "cryptoSource": "ETH"
  }
}

Purchase Limits

Day 1 of season:

Maximum 1 egg per transaction
Maximum 1 key per transaction

After Day 1:

Configurable maximum (varies by season)

Validation Rules

Maximum 5 pending purchases per user
Requested quantities must not exceed available
Requested fees must match current pricing exactly
Gateway key vouchers require:
- gatewayKeyIds array must be provided
- Array length must equal gatewayKeyVouchers count
- No duplicate IDs allowed
- Voucher count must equal egg count

Error Responses

Status	Message	Reason
400	Duplicate gateway key IDs	gatewayKeyIds contains duplicates
400	Already have 5 pending purchases	Too many pending requests
400	Requested count exceeds available	Not enough eggs/keys available
400	Requested fee doesn't match	Pricing has changed

Get Hatch Estimate {#hatch-estimate}

Calculate estimated time until a dragon egg hatches.

Endpoint

GET /api/v1/eggs/hatch/estimate/{id}

Authentication

Not required (public endpoint)

Path Parameters

Parameter	Type	Description
`id`	integer	Asset ID of the egg

Response

When egg is hatching:

{
  "minutes": 120,
  "estimatedHatchTime": 1700007200,
  "humanReadable": "approximately 2 hours and 0 minutes"
}

When egg exists but is not hatching:

{
  "minutes": -1,
  "estimatedHatchTime": -1,
  "humanReadable": "This Egg is not hatching."
}

When asset is not an egg:

{
  "minutes": -1,
  "estimatedHatchTime": -1,
  "humanReadable": "This is not an Egg."
}

Calculation Method

Uses Bitcoin block confirmations
Each block represents approximately 10 minutes
Formula: minutes = (targetBlock - currentBlock) * 10

Notes

Only works for DRAGON asset type
Only provides estimate when hatchState is HATCHING
Returns -1 values for non-hatching eggs