Run Intents

The run endpoint translates natural language into a validated action plan.

Endpoint

POST /v1/run

Request

curl -X POST https://api.grimoire.run/v1/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "YOUR_PARTNER_ID",
    "user_message": "Swap 100 USDC to ETH on Uniswap",
    "user_context": {"chain": "ethereum"}
  }'

Request Body

Field	Type	Description
`partner_id`	string	Your partner ID
`user_message`	string	Natural language description of what you want to do
`user_context.chain`	string	Target chain: `ethereum`, `arbitrum`, `optimism`, `base`, `polygon`
`stream`	boolean	Enable SSE streaming (default: `false`)

Response Types

The run endpoint returns one of two response types depending on whether the intent is clear enough to act on. When the intent is unambiguous, you get a preview. When it is ambiguous or missing information, you get clarification questions.

Preview Ready

{
  "type": "preview",
  "state": "PREVIEW_READY",
  "session_id": "sess_abc123",
  "preview": {
    "summary": "Swap 100 USDC to ETH via Uniswap V3",
    "gas_estimate": "~$1.20",
    "price_impact": "0.05%",
    "slippage": "0.2%",
    "warnings": []
  },
  "summary": "Swap 100 USDC to ETH on Uniswap V3."
}

When you receive a clarification response, submit answers via the Sessions endpoint.

Streaming

For real-time progress updates, enable SSE streaming:

Streaming Request

curl -X POST https://api.grimoire.run/v1/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "YOUR_PARTNER_ID",
    "user_message": "Swap 100 USDC to ETH on Uniswap",
    "user_context": {"chain": "ethereum"},
    "stream": true
  }'

Events are delivered with ordered sequence numbers (seq) for reliable processing:

SSE Events

data: {"seq": 1, "type": "thinking", "message": "Analyzing intent..."}
data: {"seq": 2, "type": "summary_chunk", "message": "Building action plan..."}
data: {"seq": 3, "type": "preview_ready", "state": "PREVIEW_READY"}
data: {"seq": 4, "type": "done"}

Examples

Simple swap:

Simple Swap

{"partner_id": "YOUR_PARTNER_ID", "user_message": "Swap 100 USDC to ETH on Uniswap", "user_context": {"chain": "ethereum"}}

Lending:

Lending

{"partner_id": "YOUR_PARTNER_ID", "user_message": "Lend 5000 USDC on Aave", "user_context": {"chain": "ethereum"}}

Bridge:

Bridge

{"partner_id": "YOUR_PARTNER_ID", "user_message": "Bridge 1000 USDC from Ethereum to Base", "user_context": {"chain": "ethereum"}}

Multi-step:

Multi-step

{"partner_id": "YOUR_PARTNER_ID", "user_message": "Withdraw 2000 USDC from Aave and swap half to ETH", "user_context": {"chain": "ethereum"}}

Limitations

Recurring intents (e.g., "rebalance every hour") are not yet supported as first-class actions. These currently return a clarification response.
Partial execution — if the platform cannot fully represent all requested operations, it returns a clarification rather than executing partially.