Skip to main content
POST
/
v1
/
trails
/
{trailId}
/
versions
/
{versionId}
/
executions
/
query
cURL
curl --request POST \
  --url https://trails-api.herd.eco/v1/trails/{trailId}/versions/{versionId}/executions/query \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Herd-Trail-App-Id: <herd-trail-app-id>' \
  --data '{
  "walletAddresses": [
    "<string>"
  ]
}'
{
  "totals": {
    "transactions": 123,
    "wallets": 123,
    "stepStats": {}
  },
  "walletExecutions": [
    {
      "walletAddress": "<string>",
      "farcasterData": {
        "username": "<string>",
        "pfp_url": "<string>",
        "display_name": "<string>",
        "fid": 123,
        "bio": "<string>",
        "followers": 123,
        "following": 123
      },
      "executions": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "createdAt": "<string>",
          "updatedAt": "<string>",
          "steps": [
            {
              "stepNumber": 123,
              "nodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "txHash": "<string>",
              "txBlockTimestamp": 123,
              "txBlockNumber": 123,
              "createdAt": "<string>",
              "evaluation": {
                "finalInputValues": {},
                "contractAddress": "<string>"
              }
            }
          ]
        }
      ],
      "txnsPerStep": {}
    }
  ]
}
Retrieves execution history for a trail, grouped by wallet address. Use this to display user progress, transaction feeds, and leaderboards.

​
Overview

This endpoint returns comprehensive execution data including:
  • totals: Aggregate statistics across ALL wallets (does not get filtered). Can be used to build feeds, using read nodes for extra context.
  • walletExecutions: Detailed execution data per wallet address. Used to manage the user’s execution state (current step number).

​
Request Body

{
  "walletAddresses": ["0x...", "0x..."] // filter by specific wallet addresses
}

​
Response Structure

​
Totals Object

  • transactions: Total transactions across wallets
  • wallets: Total wallets that have transacted
  • stepStats: Per-step statistics with recent transaction hashes

​
Wallet Executions Array

Each wallet contains:
  • walletAddress: Always lowercase
  • executions: Array of separate execution instances (don’t merge these)
  • farcasterData: Social profile info (username, pfp_url, display_name, etc.)
  • txnsPerStep: Transactions organized by step number

​
Farcaster Integration

Profile data includes:
  • username: Link to profile with https://farcaster.xyz/{username}
  • pfp_url: Profile picture URL
  • display_name: User’s display name
  • fid: Farcaster ID
  • bio: User bio
  • followers/following: Social metrics
Profile data can be null if user doesn’t have a Farcaster account.

​
Use Cases

  • User Progress: Show current step and transaction history for connected wallet
  • Transaction Feeds: Display recent activity across all users (i.e. X person completed Y step (link to profile, link to transaction))
  • Leaderboards: Rank users by completion or participation, combined with read node data.

​
Important Notes

  • Don’t merge executions: Each execution is independent and should be used separately
  • Filter step 0: All executions have a step 0 with nil hash - exclude from user-facing displays
  • Lowercase addresses: All wallet addresses are returned in lowercase
  • Execution selection: Users can select specific executions via latestExecutionId
  • Linking to an explorer: You can link transactions to the herd coterminal via https://herd.eco/{blockchain}/tx/hash
  1. Query with connected wallet address in walletAddresses
  2. Build step components using walletExecutions[].txnsPerStep
  3. Show social profiles using farcasterData
  4. Display aggregate stats from totals.stepStats
  5. Allow users to select an execution id for continuation, or just always use latest if you want to keep it simple.

Authorizations

​
Authorization
string
header
required

Enter your bearer token in the format Bearer <token>

Headers

​
Herd-Trail-App-Id
string
required

Application identifier for Herd Trail

Path Parameters

​
trailId
string<uuid>
required

UUIDv7 string

​
versionId
string<uuid>
required

UUIDv7 string

Body

​
walletAddresses
string[]
required

Response

Execution query results

​
totals
object
required
​
walletExecutions
object[]
required
⌘I