Execute Command

POST /execute | Auth: Required

Parse and execute a natural language command. The server interprets the command and performs the corresponding action -- such as fetching a price, checking a balance, or executing a swap.

Request

Body Parameters

Field	Type	Required	Description
command	string	Yes	Natural language instruction (max 500 characters)
wallet_address	string	No	Wallet address to use for the command. Defaults to your managed wallet if omitted.

Example Request Body

{
  "hl-key">"command": "swap 0.5 ETH to USDC on base",
  "hl-key">"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}

Supported Commands

Command Pattern	Description
"swap 0.5 ETH to USDC on base"	Execute a token swap on a specific chain
"price ETH"	Get the current price of a token
"price ETH SOL"	Get prices for multiple tokens
"balance 0x742d..."	Check the token balances of a wallet address

Response

The response structure varies depending on the type of command executed.

Common Fields

Field	Type	Description
success	boolean	Whether the request succeeded

Swap Command Response

{
  "hl-key">"success": true,
  "hl-key">"swap_id": 4821,
  "hl-key">"status": "submitted",
  "hl-key">"tx_hash": "0x8a3c...f29e"
}

Price Command Response

{
  "hl-key">"success": true,
  "hl-key">"prices": {
    "hl-key">"ETH": 3245.67,
    "hl-key">"SOL": 142.89
  }
}

Balance Command Response

{
  "hl-key">"success": true,
  "hl-key">"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "hl-key">"balances": {
    "hl-key">"ETH": "1.2345",
    "hl-key">"USDC": "500.00"
  }
}

Errors

Status	Error	Cause
400	"command is required"	Missing command in request body
400	"Command exceeds 500 character limit"	The command string is too long
400	"Unable to parse command"	The command could not be interpreted
401	"Unauthorized"	Missing or invalid API key
404	"No managed wallet found"	No wallet available and none specified in wallet_address
500	"Execution failed"	Internal error while processing the command

Code Examples

curl

-kw">curl -X POST https://api.suwappu.bot/v1/agent/execute \
  -H -str">"Authorization: Bearer suwappu_sk_your_api_key" \
  -H -str">"Content-Type: application/json" \
  -d -str">'{-str">"command": -str">"swap 0.5 ETH to USDC on base"}'

Python

import requests

response = requests.post(
    class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/execute",
    headers={class="hl-str">"Authorization": class="hl-str">"Bearer suwappu_sk_your_api_key"},
    json={class="hl-str">"command": class="hl-str">"swap 0.5 ETH to USDC on base"},
)

data = response.json()
if data[class="hl-str">"success"]:
    print(data)

TypeScript

const response = await fetch(
  class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/execute",
  {
    method: class="hl-str">"POST",
    headers: {
      Authorization: class="hl-str">"Bearer suwappu_sk_your_api_key",
      class="hl-str">"Content-Type": class="hl-str">"application/json",
    },
    body: JSON.stringify({
      command: class="hl-str">"swap 0.5 ETH to USDC on base",
    }),
  }
);

const data = await response.json();
if (data.success) {
  console.log(data);
}