> ## Documentation Index
> Fetch the complete documentation index at: https://spiceflow-docs.spicenet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /intent/{intentId}/step/{stepId}

> Execute a specific intent step and return the execution results

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

Execute a specific intent step and return the execution results.

## Endpoint

```http theme={null}
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

| Parameter  | Type     | Required | Description                                                     |
| ---------- | -------- | -------- | --------------------------------------------------------------- |
| `intentId` | `string` | Yes      | The unique intent identifier (signature of chainBatches)        |
| `stepId`   | `number` | Yes      | The step index \[0, n) representing the chain batch array index |

## Request Body

```json theme={null}
{
  "executeOptions": {
    "dryRun": false,
    "gasLimit": 500000
  }
}
```

### Request Parameters

| Field                     | Type      | Required | Description                                    |
| ------------------------- | --------- | -------- | ---------------------------------------------- |
| `executeOptions.dryRun`   | `boolean` | No       | If true, simulate execution without committing |
| `executeOptions.gasLimit` | `number`  | No       | Gas 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)

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

### Response Fields

| Field              | Type     | Description                                       |
| ------------------ | -------- | ------------------------------------------------- |
| `intentId`         | `string` | The intent identifier                             |
| `stepId`           | `number` | The executed step index                           |
| `status`           | `string` | Execution status                                  |
| `transactionHash`  | `string` | Hash of the execution transaction (if applicable) |
| `chainId`          | `number` | Chain ID where the step was executed              |
| `executionResults` | `object` | Results of the step execution                     |

### Step Status

| Status      | Description                        |
| ----------- | ---------------------------------- |
| `pending`   | Step is waiting to be executed     |
| `executing` | Step is currently being executed   |
| `success`   | Step executed successfully         |
| `error`     | Step execution failed              |
| `reverted`  | Step transaction reverted on-chain |
| `skipped`   | Step was skipped due to conditions |

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "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

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Failed to execute intent step",
    "code": "EXECUTION_ERROR"
  }
}
```

## Example Request

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

## Example Usage

```bash theme={null}
# 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