Request & Response Format

Request & Response Format

Request Fields

Required Fields

Field	Type	Description
prompt	string	Natural language trading instruction
walletAddress	string	Your wallet address (EVM 0x... or Solana)
provider	string	Your agent/integration name for tracking

Optional Fields

Field	Type	Default	Description
chain	string	—	Preferred chain (e.g., "base", "ethereum", "arbitrum")
slippage	number	1	Slippage tolerance percentage
async	boolean	false	Use async mode for long operations

Example Request

{
  "prompt": "swap 50 USDC for ETH on arbitrum",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7AAAA",
  "provider": "my-trading-bot",
  "chain": "arbitrum",
  "slippage": 0.5,
  "async": false
}

---

Prompt Best Practices

Your prompt quality directly affects the response. Follow these guidelines to avoid wasted API calls.

✅ Good Prompts

Prompt	Why It's Good
"Buy $50 worth of ETH on Base"	Clear action, amount, token, chain
"Swap 100 USDC for WETH on Arbitrum"	All details specified
"Bridge 50 USDC from Ethereum to Base"	Source and destination chains
"What is the price of 0x4ed4...fed on Base?"	Contract address for obscure tokens
"Send 10 USDC to 0x742d...AAAA on Base"	Recipient address included

❌ Bad Prompts

Prompt	Problem	Better Version
"Buy some crypto"	No token, amount, or chain	"Buy $50 of ETH on Base"
"Get me ETH"	No amount or chain	"Buy $100 of ETH on Arbitrum"
"Trade tokens"	Missing everything	"Swap 50 USDC for ETH on Base"
"What's the price?"	No token specified	"What's the price of ETH on Base?"
"Buy XYZ"	Ambiguous token, no chain	"Buy $20 of XYZ on Base" or use CA

Required Information by Operation

Operation	Required Info
Buy	Token, amount (USD or token), chain
Sell	Token, amount, chain
Swap	From token, to token, amount, chain
Bridge	Token, amount, source chain, destination chain
Send	Token, amount, recipient address, chain
Price Check	Token (symbol or CA), chain

---

Response Types

Every response includes a type field indicating what kind of result was returned:

Type	Description	Has Transactions	Charged
transaction	Trade prepared, ready to sign	✅ Yes	✅ $0.20
info	Informational response or clarification request	❌ No	✅ $0.20
error	Something went wrong	❌ No	✅ $0.20

⚠️ Important: You are charged $0.20 for every API call, regardless of the response type.

---

Transaction Response

When your prompt results in a tradeable action (buy, sell, swap, bridge, etc.):

{
  "success": true,
  "jobId": "4c6f5fb5-fdaa-49cb-8a16-5088156f5231",
  "status": "completed",
  "type": "transaction",
  "response": "Your swap is ready! Trading 50 USDC for approximately 0.024 ETH on Arbitrum.",
  
  "operation": {
    "operation_id": "op_1771094491979_wk6bp2x",
    "operation_type": "swap",
    "token_symbol": "USDC",
    "token_address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "token_out_symbol": "ETH",
    "token_out_address": "native",
    "amount": 50,
    "amount_type": "token",
    "chain": "arbitrum",
    "slippage_tolerance": 0.5
  },
  
  "transactions": [
    {
      "type": "swap",
      "description": "Swap USDC for ETH",
      "chain": "arbitrum",
      "sequence": 1,
      "to": "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
      "data": "0xe21fd0e9000000000000000000000000...",
      "value": "0",
      "chainId": 42161,
      "gas": "450000",
      "gasPrice": null,
      "maxFeePerGas": null,
      "maxPriorityFeePerGas": null,
      "expiresAt": 1771094646794
    }
  ],
  
  "transaction_data": {
    "quote": {
      "inputToken": "USDC",
      "outputToken": "ETH",
      "inputAmount": "50000000",
      "outputAmount": "0.024",
      "priceImpact": "0.01",
      "estimatedGas": "450000"
    },
    "slippage": 0.5,
    "usdValue": 50.00
  },
  
  "processingTime": 18532
}

Transaction Object Fields

Field	Type	Description
type	string	Transaction type: swap, bridge, transfer, wrap, etc.
description	string	Human-readable description
chain	string	Target chain
sequence	number	Order for multi-tx operations
to	string	Contract address to call
data	string	Encoded calldata
value	string	Native token value (wei)
chainId	number	Chain ID
gas	string	Estimated gas limit
expiresAt	number	Quote expiration (Unix ms)

Operation Object Fields

Field	Type	Description
operation_id	string	Unique operation identifier
operation_type	string	buy, sell, swap, bridge, send, etc.
token_symbol	string	Input token symbol
token_address	string	Input token address
token_out_symbol	string	Output token symbol (for swaps)
token_out_address	string	Output token address
amount	number	Trade amount
amount_type	string	usd or token
chain	string	Target chain

---

Info Response

When your prompt is informational (price check, balance, etc.):

{
  "success": true,
  "jobId": "abc-123",
  "status": "completed",
  "type": "info",
  "response": "ETH is currently trading at $2,063.45 on Base. The 24h change is +2.3%.",
  
  "operation": null,
  "transactions": [],
  "transaction_data": {},
  
  "data": {
    "tokenPrice": 2063.45,
    "priceChange24h": 2.3,
    "chain": "base"
  },
  
  "processingTime": 3200
}

---

Clarification Response

When your prompt is unclear or missing information:

{
  "success": true,
  "jobId": "xyz-456",
  "status": "completed",
  "type": "info",
  "response": "I'd be happy to help you trade! To proceed, please specify:\n\n1. **Which token** do you want to buy?\n2. **How much** (e.g., $50 or 100 tokens)?\n3. **Which chain** (e.g., Base, Ethereum, Arbitrum)?",
  
  "operation": null,
  "transactions": [],
  "transaction_data": {},
  
  "processingTime": 2100
}

⚠️ Note: This still costs $0.20. Validate prompts before sending.

---

Error Response

When something goes wrong:

{
  "success": false,
  "jobId": "xyz-789",
  "status": "failed",
  "type": "error",
  "error": "Insufficient balance. You have 5 USDC but need 50 USDC for this trade.",
  
  "operation": null,
  "transactions": [],
  
  "processingTime": 2100
}

Common Errors

Error	Cause
Insufficient balance	Wallet doesn't have enough tokens
Token not found	Unknown token symbol or address
Chain not supported	Requested chain isn't available
Quote expired	Took too long, quote is stale
Honeypot detected	Token failed security scan

---

Multi-Transaction Operations

Some operations require multiple transactions (e.g., approve + swap):

{
  "transactions": [
    {
      "type": "approve",
      "description": "Approve USDC spending",
      "sequence": 1,
      "to": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "data": "0x095ea7b3...",
      "value": "0",
      "chainId": 42161,
      "gas": "50000"
    },
    {
      "type": "swap",
      "description": "Swap USDC for ETH",
      "sequence": 2,
      "to": "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
      "data": "0xe21fd0e9...",
      "value": "0",
      "chainId": 42161,
      "gas": "450000"
    }
  ]
}

Execute transactions in sequence order. Wait for each transaction to confirm before sending the next.

---

Bridge Response

Bridge operations include source and target chain info:

{
  "type": "transaction",
  "operation": {
    "operation_type": "bridge",
    "token_symbol": "USDC",
    "amount": 100,
    "chain": "arbitrum",
    "target_chain": "base"
  },
  "transactions": [
    {
      "type": "bridge",
      "description": "Bridge 100 USDC from Arbitrum to Base",
      "chain": "arbitrum",
      "to": "0xBridgeContract...",
      "data": "0x...",
      "value": "0",
      "chainId": 42161,
      "gas": "300000"
    }
  ],
  "transaction_data": {
    "bridge": {
      "provider": "across",
      "sourceChain": "arbitrum",
      "targetChain": "base",
      "estimatedTime": "2-5 minutes",
      "fee": "0.05"
    }
  }
}

---

Perpetuals Response (Avantis)

For perpetual trades on Avantis:

{
  "type": "transaction",
  "operation": {
    "operation_type": "perp_long",
    "token_symbol": "ETH",
    "amount": 100,
    "chain": "base"
  },
  "transactions": [
    {
      "type": "perp_open",
      "description": "Open 10x long ETH position",
      "to": "0xAvantisContract...",
      "data": "0x...",
      "chainId": 8453,
      "gas": "500000"
    }
  ],
  "transaction_data": {
    "perp": {
      "side": "long",
      "leverage": 10,
      "size": 100,
      "entryPrice": 2063.45,
      "liquidationPrice": 1857.10
    }
  }
}

---

Prediction Markets Response (Myriad)

For prediction market trades on Myriad:

{
  "type": "transaction",
  "operation": {
    "operation_type": "prediction_market_buy",
    "amount": 10,
    "chain": "base"
  },
  "transactions": [
    {
      "type": "prediction_buy",
      "description": "Buy YES shares on market",
      "to": "0xMyriadContract...",
      "data": "0x...",
      "chainId": 8453,
      "gas": "250000"
    }
  ],
  "transaction_data": {
    "prediction": {
      "market": "Will ETH hit $3000 by March?",
      "outcome": "YES",
      "shares": 15.5,
      "avgPrice": 0.645
    }
  }
}

---

Async Mode

When using async: true, the initial response is different:

Initial Response (202)

{
  "success": true,
  "jobId": "4c6f5fb5-fdaa-49cb-8a16-5088156f5231",
  "status": "processing",
  "message": "Job created. Poll GET /v1/jobs/:jobId for results."
}

Poll Until Complete

# Poll every 2 seconds
while status == "processing":
  response = GET /v1/tator/jobs/{jobId}?walletAddress={wallet}
  status = response.status
  sleep(2)

Final Response

Same format as sync mode (transaction, info, or error).

---

Signing Transactions

Once you receive a transaction response, sign and broadcast each transaction:

for (const tx of response.transactions) {
  // Sign with your wallet
  const signedTx = await wallet.signTransaction({
    to: tx.to,
    data: tx.data,
    value: BigInt(tx.value),
    gas: BigInt(tx.gas),
    chainId: tx.chainId
  });
  
  // Broadcast
  const hash = await provider.sendTransaction(signedTx);
  
  // Wait for confirmation
  await provider.waitForTransaction(hash);
}

Important: Transactions have an expiresAt timestamp. Sign and broadcast promptly to avoid quote expiration.

---

Next Steps

• Example Flows — Complete code examples