⚙️Foraging API

Swagger UI

Access the Foraging APIs

Unlike the other API endpoints that rely on on-chain token IDs for identifying unique NFTs, the off-chain foraging endpoints use a combination of different IDs to return results. It’s important to know which ID to use and when.

TokenID

An on-chain token ID that can be found using chain explorers.

BaseID

A universal placeholder that identifies an item in the foraging system before a unique instance of the item being crafted. BaseIDs can be found in the Crafting > Blueprints section of the Appendix documentation (use the HEX Base ID value).

InternalID

A specific instance of an item in the off-chain foraging game.

When an Item is crafted, the system uses the BaseID to create an InternalID of that item’s instance. When the item is moved on-chain, a TokenID is minted along with it.

Blueprints are minted directly to wallets and so do not have an InternalID.

Unix Epoch

Some APIs reference time periods displayed as a Unix Epoch. This timestamp can be found by using a converter.

Unix Time Stamp - Epoch Converter

---

Birds

/api/chikns

Returns detailed information on bird stats, including traits. The trait details include information on applicable bonuses to foraging, as well as rarity information.

TokenID (optional)

The chikn token ID the operation should be performed on. No token ID lists all birds.

page

Results page for birds (if no TokenID is specified)

limit

Number of results per page (if no TokenID is specified)

---

/api/roostrs

Returns detailed information on bird stats, including traits. The trait details include information on applicable bonuses to foraging, as well as rarity information.

TokenID (optional)

The roostr token ID the operation should be performed on. No token ID lists all birds.

page

Results page for birds.

limit

Number of results per page.

FarmLand

/api/farmland/{TokenID}

Returns detailed information on a FarmLand token, including fertility, available item slots, WormFarm information, size, and tile details with breakdowns of resource availability and rarity.

TokenID (Required)

The FarmLand token ID the operation should be performed on.

---

/api/farmland/{TokenID}/forage

Returns information on the forage state of a FarmLand token. FarmLand being actively foraged details information sorted by bird including start and end time, bird trait bonuses, and any active items.

TokenID (Required)

The FarmLand token ID the operation should be performed on.

---

/api/farmland/{TokenID}/wormfarm

Returns information on a WormFarm associated with a FarmLand token, including depth dug, depth filled with worm, cooldowns, worm deployed, and max worm capacity.

TokenID (Required)

The FarmLand token ID the operation should be performed on.

Wallet

/api/wallets

Lists all wallets that have interacted with the off-chain foraging APIs.

page

Results page for wallets.

limit

Number of results per page.

---

/api/{Wallet}/balances

Lists the off-chain foraging stats of a wallet, including off-chain token balances, silo capacities, resources used in crafting, and resource balances.

Wallet (required)

The wallet address the operation should be performed on.

---

/api/{Wallet}/items

Lists the off-chain Item inventory of a wallet. Item results include the TokenID (if available), the InternalID, the baseID, number of uses, max use, details on the last item use, and crafting costs.

Wallet (required)

The wallet address the operation should be performed on.

page

Results page for Items.

limit

Number of results per page.

---

/api/{Wallet}/forage/history

Lists the results of historical forages by a wallet grouped by bird. Results include the trait bonus of the bird, any equipped bird items, forage start and end time (in Unix timestamp), tiles foraged, the number of rolls per tile, forage results, and claim time.

Wallet (required)

The wallet address the operation should be performed on.

page

Results page for history.

limit

Number of results per page.

forageEnd

Limit results to those before the forageEnd time. Note that the time must be converted to a Unix timestamp.

Blueprint

/api/blueprint/baseId/{baseID}

Returns information on blueprints using a BaseID, including supply, crafting costs, description, max forage uses, and type. This endpoint can also be used with an Item BaseID.

baseID (required)

The BaseID of the Item or Blueprint the operation should be performed on.

---

/api/blueprint/instance/{tokenID}

Returns information on blueprints using an on-chain TokenID, including supply, crafting costs, description, max forage uses, and type.

tokenID (required)

The BaseID of the blueprint the operation should be performed on.

Item

/api/item/instance/{tokenID}

Returns information on items using an on-chain TokenID, including supply, total minted, uses, max uses, description, type, and on which token the Item is equipped.

tokenID (required)

The TokenD of the Item the operation should be performed on.

---

/api/blueprint/internal/{internalID}

Returns information on Items using an InternalID, including supply, total minted, uses, max uses, description, type, and on which token the Item is equipped.

internalID (required)

The InternalID of the blueprint the operation should be performed on.