# Executor API

**API Overview**

The Executor API enables developers to automate multi-chain workflows via RESTful endpoints, leveraging Agent-001's AI for strategy formulation and ERC-7645 for trustless execution.

```python
# Python SDK Example: Initiate a Cross-Chain Swap  
from agent001_sdk import WorkflowClient  

client = WorkflowClient(api_key="AGPT_...", chain_prefs=["arbitrum", "base"])  

response = client.execute_workflow(  
    name="DEX Arbitrage",  
    actions=[  
        {  
            "type": "swap",  
            "from": "ETH",  
            "to": "USDC",  
            "amount": "0.5",  
            "slippage": 0.5  # 0.5% max  
        },  
        {  
            "type": "bridge",  
            "destination": "base",  
            "protocol": "stargate"  
        }  
    ]  
)  

print(f"Execution ID: {response.execution_id}")  
```

***

#### **Core Endpoints**

**1. Submit Workflow**

**Endpoint**: `POST /v1/workflows`\
**Request**:

```json
{  
  "name": "Enterprise Payroll",  
  "schedule": "0 0 * * FRI",  // Cron: Weekly Friday  
  "actions": [  
    {  
      "type": "convert",  
      "from": "USDC",  
      "to": "EURT",  
      "amount": "250000",  
      "route_optimizer": {  
        "priority": "cost"  
      }  
    },  
    {  
      "type": "multisend",  
      "recipients": [  
        {"address": "0x...", "amount": "60%"},  
        {"address": "0x...", "amount": "40%"}  
      ]  
    }  
  ],  
  "compliance": {  
    "jurisdictions": ["EU", "SG"]  
  }  
}  
```

**Response**:

```json
{  
  "status": "queued",  
  "execution_id": "wf_3abx...9yz2",  
  "cost_estimate": {  
    "total_usd": 14.20,  
    "gas_breakdown": {"arbitrum": 0.0031, "base": 0.0014}  
  }  
}  
```

***

#### **Workflow Definition Schema**

**YAML Structure**

```yaml
name: Supplier_Payout_Asia  
trigger:  
  frequency: "daily 18:00 HKT"  
actions:  
  - action: convert  
    params:  
      from: USDC  
      to: SGD  
      amount: 150000  
      dex: uniswap_x  
  - action: multisend  
    params:  
      recipients:  
        - 0xSupplierA: 75000  
        - 0xSupplierB: 75000  
compliance:  
  tax_forms:  
    - GST_SG_2025  
```

***

#### **Execution Flow**

```mermaid
sequenceDiagram  
    User->>API: POST /v1/workflows  
    API->>AI Engine: Validate & Optimize  
    AI Engine->>Router: Select Chains/DEXs  
    Router->>Executor: Sign & Broadcast  
    Executor->>Chains: Ethereum, Base, etc.  
    Chains-->>Auditor: ZK-Proof Generation  
    Auditor-->>User: Final Report  
```

***

#### **Error Handling**

| HTTP Code | Error Type               | Resolution                    |
| --------- | ------------------------ | ----------------------------- |
| 429       | Rate Limit Exceeded      | Retry with `Retry-After: 30s` |
| 400       | Invalid Compliance Rules | Check `/v1/compliance/specs`  |
| 503       | Chain Congestion         | Use `fallback_chains` param   |

**Example Error Response**:

```json
{  
  "error": "INSUFFICIENT_LIQUIDITY",  
  "detail": "USDC-SGD pool < $100k on Arbitrum. Suggested alt: Polygon zkEVM",  
  "retry_in": 120  
}  
```

***

#### **Security & Signing**

All requests require HMAC-SHA256 signatures:

```javascript
// JavaScript Signature Example  
const crypto = require('crypto');  

const signRequest = (apiKey, secret, body) => {  
  const timestamp = Date.now().toString();  
  const payload = `${timestamp}${JSON.stringify(body)}`;  
  const signature = crypto  
    .createHmac('sha256', secret)  
    .update(payload)  
    .digest('hex');  

  return {  
    headers: {  
      'X-AGPT-Key': apiKey,  
      'X-AGPT-Signature': signature,  
      'X-AGPT-Timestamp': timestamp  
    }  
  };  
};  
```

***

#### **Performance & Limits**

| Resource             | Tier 1 (Free) | Tier 3 (Enterprise) |
| -------------------- | ------------- | ------------------- |
| Requests/min         | 20            | 1,200               |
| Concurrent Workflows | 5             | 500                 |
| SLA                  | 99%           | 99.99%              |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://agent-gpt.gitbook.io/agent-gpt/agent-001/executor-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.