Skip to main content

​
POST /intent//execute/

Execute a specific intent step and return the execution results.

​
Endpoint

POST /intent/{intentId}/execute/{stepId}

​
Description

This endpoint executes a specific step in an intent workflow. Each call performs one unit of work, triggering checks, sending transactions, and returning the execution results. This is an active execution endpoint that modifies state and performs side effects.

​
Path Parameters

ParameterTypeRequiredDescription
intentIdstringYesThe unique intent identifier (signature of chainBatches)
stepIdnumberYesThe step index [0, n) representing the chain batch array index

​
Request Body

{
  "executeOptions": {
    "dryRun": false,
    "gasLimit": 500000
  }
}

​
Request Parameters

FieldTypeRequiredDescription
executeOptions.dryRunbooleanNoIf true, simulate execution without committing
executeOptions.gasLimitnumberNoGas limit for transaction execution

​
How It Works

  • Intent ID: The signature of the chainBatches (similar to Solana’s approach)
  • Step ID: Integer representing the index of the chain batch in the array
  • Execution: Calling this endpoint triggers the actual work for that step
  • Unit of Work: Each call performs one discrete unit of work in the intent workflow

​
Response

​
Success Response (200)

{
  "success": true,
  "data": {
    "intentId": "0xabcdef1234567890...",
    "stepId": 0,
    "status": "completed",
    "transactionHash": "0x1234567890abcdef...",
    "chainId": 1,
    "executionResults": {
      "success": true,
      "gasUsed": 21000
    }
  }
}

​
Response Fields

FieldTypeDescription
intentIdstringThe intent identifier
stepIdnumberThe executed step index
statusstringExecution status
transactionHashstringHash of the execution transaction (if applicable)
chainIdnumberChain ID where the step was executed
executionResultsobjectResults of the step execution

​
Step Status

StatusDescription
pendingStep is waiting to be executed
executingStep is currently being executed
successStep executed successfully
errorStep execution failed
revertedStep transaction reverted on-chain
skippedStep was skipped due to conditions

​
Error Responses

​
400 Bad Request

{
  "success": false,
  "error": {
    "message": "Invalid stepId: must be integer between 0 and n-1"
  }
}

​
404 Not Found

Note: The POST execution endpoint currently returns 500 for most failures. Use the GET status endpoint for 404 (not found) semantics.

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "message": "Failed to execute intent step",
    "code": "EXECUTION_ERROR"
  }
}

​
Example Request

curl -X POST /intent/0xabcdef1234567890.../execute/0 \
  -H "Content-Type: application/json" \
  -d '{
    "executeOptions": {
      "dryRun": false,
      "gasLimit": 500000
    }
  }'

​
Example Usage

# Execute the first step of an intent
curl -X POST /intent/0xabcdef1234567890.../execute/0 \
  -H "Content-Type: application/json" \
  -d '{"executeOptions": {"dryRun": false}}'

# Response shows execution results
{
  "success": true,
  "data": {
    "intentId": "0xabcdef1234567890...",
    "stepId": 0,
    "status": "completed",
    "transactionHash": "0x1234567890abcdef...",
    "chainId": 1,
    "executionResults": {
      "success": true,
      "gasUsed": 21000
    }
  }
}

# Execute the next step
curl -X POST /intent/0xabcdef1234567890.../execute/1 \
  -H "Content-Type: application/json" \
  -d '{"executeOptions": {"dryRun": false}}'

# Continue until all steps are complete

​
Workflow Pattern

  1. Submit Intent: Use POST /transaction/submit to create the intent
  2. Execute Steps: Call POST /intent/{id}/execute/{i} for each step i = 0, 1, 2, …
  3. Check Results: Each response contains the execution results for that step
  4. Continue: Execute steps sequentially until the intent is complete

​
Notes

  • Steps must be executed in order (0, 1, 2, …)
  • Each step corresponds to a chain batch in the original array
  • The endpoint performs actual execution with side effects (not idempotent)
  • Failed steps may be retryable depending on the failure reason
  • Intent data is persisted in the database for reliable execution tracking
  • Use dryRun: true to simulate execution without committing changes