Skip to main content
POST
/
v1
/
trails
/
{trailId}
/
versions
/
{versionId}
/
steps
/
{stepNumber}
/
evaluations
/
cURL
curl --request POST \
  --url https://trails-api.herd.eco/v1/trails/{trailId}/versions/{versionId}/steps/{stepNumber}/evaluations/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Herd-Trail-App-Id: <herd-trail-app-id>' \
  --data '{
  "execution": {
    "type": "new"
  },
  "walletAddress": "<string>",
  "userInputs": {}
}'
{
  "nodeType": "write_function",
  "finalInputValues": {},
  "args": [
    "<any>"
  ],
  "payableAmount": "<string>",
  "contractAddress": "<string>",
  "callData": "<string>"
}
Processes user inputs for a trail step and returns the transaction calldata needed for blockchain submission.

​
Overview

This endpoint takes user-provided inputs for a step and returns:
  • callData: Transaction calldata for wallet signing
  • contractAddress: Target contract address
  • payableAmount: Native token value to send
  • finalInputValues: Processed input values used

​
Input Value Processing

The system processes different input types based on their derive_method:
  • user_input: Consumer must provide the value
  • user_wallet: Uses the connected wallet address
  • creator_hardcoded: Creator pre-filled the value
  • relational: Derived from other contract nodes
  • step_execution: Gets transaction hash from specific step execution
  • code: Derived from TypeScript code execution
  • encode_calldata: The encoded calldata of a write function

​
Request Body

{
  "walletAddress": "0x...",
  "userInputs": {
    "nodeId": {
      "some.dot.path.to.input": {
        "value": "someValue" // always wrap in quotes, even numbers
      },
      "another.input.path": {
        "value": "anotherValue"  
      }
    }
  },
  "execution": { 
    "type": "latest" | "new" | "manual",
    "executionId": "uuid" // only for manual type
  }
}

​
Array Input Handling

Arrays use flattened dot notation with indices:

​
Simple Arrays

"userInputs": {
  "nodeId": {
    "inputs.someArray": { "value": "" }, // always empty string for array parent
    "inputs.someArray.0": { "value": "firstElement" },
    "inputs.someArray.1": { "value": "secondElement" }
  }
}

​
Tuple Arrays

"userInputs": {
  "nodeId": {
    "inputs.someTupleArray": { "value": "" },
    "inputs.someTupleArray.0.componentA": { "value": "value1" },
    "inputs.someTupleArray.0.componentB": { "value": "value2" },
    "inputs.someTupleArray.1.componentA": { "value": "value3" },
    "inputs.someTupleArray.1.componentB": { "value": "value4" }
  }
}

​
Integer Decimals

For integer types, decimal multipliers may be automatically handled. You can check “appliedDecimals” in the trail guidebook.

​
Response Structure

{
  "finalInputValues": {
    "input.path": "processedValue"
  },
  "payableAmount": "1000000000000000000", // in wei
  "contractAddress": "0x...", // target contract
  "callData": "0x..." // transaction data
}

​
Source Nodes and Relationships

Input values can reference other nodes through:
  • allSourceNodesForThisStep: Available nodes for this step
  • derivedFromNodeId: Specific node an input derives from
  • Previous step data builds up as consumers progress

​
Error Handling

Input validation errors appear in:
  • Response validation messages
  • finalInputValues object showing processed results

​
Best Practices

  1. Exact Matching: Use exact nodeId and input names from step data
  2. Flattened Paths: Maintain full dot notation paths, don’t truncate
  3. Array Defaults: Copy from arrayDefaults when adding array elements
  4. String Values: Always wrap values in quotes in JSON
  5. Required Only: Only submit user_input fields from arrayDefaults

​
Workflow

  1. Get requiredUserInputs from trail guidebook step data
  2. Collect user input for all user_input derive methods
  3. Submit to this endpoint with proper formatting
  4. Use returned calldata for wallet transaction
  5. Save transaction hash to executions endpoint

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

​
stepNumber
number
required

Body

​
execution
object
required
  • Option 1
  • Option 2
  • Option 3
​
walletAddress
string
required
​
userInputs
object
required

Response

200 - application/json

Step evaluation completed successfully

  • Option 1
  • Option 2
​
nodeType
enum<string>
required
Available options:
write_function
​
finalInputValues
object
required
​
args
any[]
required
​
payableAmount
string
required
​
contractAddress
string
required
​
callData
string
required
⌘I