Skip to main content
The Herd Trails API enables developers to integrate blockchain trail execution and management into their applications. This RESTful API provides endpoints for retrieving trail configurations, managing user executions, and interacting with smart contracts.
The easiest way to integrate the API is to go to the trail overlook and copy the Guidebook prompt/link. For debugging, you can also use the overlook to submit send/read requests, which will generate you example cURL and response results that you can prompt LLMs with.

​
Base API URL

https://trails-api.herd.eco

​
Authentication

All API requests do not require an API key, but there is a rate limit in place. If you require higher limits then please create an api key by going to your trail apps then create new app -> API keys -> create key. The API key header is -H Herd-Trail-Api-Key: <api_key>
You are always required to set a Herd-Trail-App-Id header with an app id for all requests. This is DIFFERENT from the api key, and is used for attributing your transactions from your app, when will make you eligible for rewards and better discovery. You can create an app id here.

​
Core Concepts

​
Trails

Trails are multi-step blockchain workflows that guide users through complex DeFi operations, NFT interactions, or other smart contract activities. Each trail comes with a guidebook (a txt file) that explains how to build/integrate it into an app, automation, chatbot, etc. This can be found in the trail overlook (like this one).

​
Versions

Each trail can have multiple versions, allowing for updates and improvements while maintaining backward compatibility.
Currently, trails only have one version. There will be an update soon with version control for each change after publishing.

​
Executions

Executions track a user’s progress through a trail, recording transaction hashes and step completion status.

​
Nodes

Nodes represent individual operations within a trail step - reading from contracts, executing transactions, or processing data.

​
Getting Started

  1. Retrieve a trail: Use the guidebook endpoints to get trail configuration
  2. Collect user inputs: Gather required information for each step
  3. Get transaction data: Use the evaluations endpoint to generate calldata
  4. Execute transaction: Have users sign and submit the transaction
  5. Save progress: Record the transaction hash via the executions endpoint

​
Rate Limiting

  • Avoid high-frequency polling of endpoints
  • Cache guidebook data when possible
  • Use execution queries efficiently

​
Support

For questions about the API or trail creation, contact the Herd team.
⌘I