Market.ai Conversational Trading Guide

Trade crypto and interact with prediction markets through natural language. Talk to an AI assistant that can execute trades, query your portfolio, analyze markets, and interact with Polymarket -- all through a simple chat interface.

Overview

The conversational trading interface is an AI-powered layer on top of Market.ai's market intelligence infrastructure. It processes natural language messages, determines intent (market query, trade, portfolio check, etc.), and takes the appropriate action:

• Market queries -- "What's happening with BTC?" calls Market.ai's MCP tools and returns analyzed market data
• Trade execution -- "Buy 0.5 BTC" parses the intent, proposes the trade, and waits for your explicit confirmation before executing via your exchange API credentials
• Portfolio queries -- "What's my P&L today?" reads your positions from the broker API
• Polymarket queries -- "What are the BTC hourly odds?" fetches prediction market data
• Conditional orders -- "Buy SOL if it drops below $140" sets up a price trigger

Every trade requires explicit confirmation. The AI proposes, you confirm.

Quick Start

1. Get your API key (chat is available on all tiers, including free)
2. Store your exchange credentials via the /v1/credentials endpoint (see Broker Setup)
3. Start chatting:

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "What is BTC doing right now?"}' \
  https://api.market-ai.dev/v1/chat

API Endpoints

Send a Message

Send a natural language message to the AI trading assistant.

Request body:

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Buy 0.5 BTC at market",
    "sessionId": "chat_abc123"
  }' \
  https://api.market-ai.dev/v1/chat

If sessionId is omitted, a new session is created. Pass the returned sessionId on subsequent messages to maintain conversation context.

Response:

{
  "ok": true,
  "data": {
    "sessionId": "chat_abc123",
    "response": "I'll place a market buy order for 0.5 BTC/USDT on Binance at approximately $67,450. Estimated cost: $33,725.\n\nPlease confirm to execute this trade.",
    "actions": [
      {
        "id": "act_xyz789",
        "intent": {
          "action": "buy",
          "symbol": "BTC/USDT",
          "quantity": "0.5",
          "orderType": "market"
        },
        "status": "pending",
        "createdAt": 1708776300000,
        "expiresAt": 1708776600000
      }
    ],
    "contextUsed": ["market_data", "portfolio"]
  },
  "meta": { "timestamp": 1708776300000 }
}

When the response includes actions, the AI is proposing trades that need your confirmation.

Confirm a Trade

Confirm and execute a pending trade action. The session_id query parameter is required.

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  "https://api.market-ai.dev/v1/chat/confirm/act_xyz789?session_id=chat_abc123"

Response (success):

{
  "ok": true,
  "data": {
    "action_id": "act_xyz789",
    "status": "executed",
    "execution": {
      "orderId": "ord_123",
      "exchange": "binance",
      "fillPrice": "67455.20",
      "fillQuantity": "0.5",
      "fees": "16.86",
      "timestamp": 1708776310000
    }
  },
  "meta": { "timestamp": 1708776310000 }
}

Response (expired):

{
  "ok": false,
  "error": {
    "code": "action_expired",
    "message": "This action has expired. Please create a new trade request."
  }
}

Response (already confirmed):

{
  "ok": false,
  "error": {
    "code": "invalid_status",
    "message": "Action is already 'executed'. Cannot confirm."
  }
}

Cancel a Trade

Cancel a pending trade action. The session_id query parameter is required.

curl -X DELETE -H "Authorization: Bearer mk_live_abc123..." \
  "https://api.market-ai.dev/v1/chat/cancel/act_xyz789?session_id=chat_abc123"

Response:

{
  "ok": true,
  "data": {
    "action_id": "act_xyz789",
    "status": "cancelled"
  },
  "meta": { "timestamp": 1708776310000 }
}

Conversation History

Get paginated conversation history for a session.

curl -H "Authorization: Bearer mk_live_abc123..." \
  "https://api.market-ai.dev/v1/chat/history?session_id=chat_abc123&limit=20"

Response:

{
  "ok": true,
  "data": {
    "session_id": "chat_abc123",
    "items": [
      {
        "role": "user",
        "content": "What is BTC doing?",
        "timestamp": 1708776200000,
        "sessionId": "chat_abc123"
      },
      {
        "role": "assistant",
        "content": "BTC is trading at $67,450 with bullish momentum...",
        "timestamp": 1708776201000,
        "sessionId": "chat_abc123"
      }
    ],
    "total": 12,
    "limit": 20,
    "offset": 0
  },
  "meta": { "timestamp": 1708776300000 }
}

Pending Actions

List all pending (non-expired) trade actions for a session.

curl -H "Authorization: Bearer mk_live_abc123..." \
  "https://api.market-ai.dev/v1/chat/actions?session_id=chat_abc123"

Conversation Examples

Market Queries

The AI uses Market.ai's tools to fetch real-time data and provide analysis.

You: "What's happening with ETH?"

AI: ETH/USDT is trading at $3,245 with neutral momentum. Key observations:

• Spread: 2.1 bps on Binance, within normal range
• OBI: -0.05 (slightly ask-heavy, mild sell pressure)
• Funding: 0.008% on Binance (normal)
• No active signals for ETH
• Volume: $2.1B across exchanges in the last 24h

You: "Any whale activity?"

AI: No whale movements detected for ETH in the past 24 hours. Last significant whale trade was 3 days ago -- a $1.2M sell on Coinbase.

Trade Execution

You: "Buy 0.5 BTC"

AI: I'll place a market buy order for 0.5 BTC/USDT on Binance at approximately $67,450.

• Estimated cost: $33,725
• Fee estimate: ~$16.86 (0.05%)
• Max slippage: 0.5%

Please confirm to execute. [Action: act_xyz789, expires in 5 minutes]

You: (confirm via POST/v1/chat/confirm/act_xyz789)

AI: Trade executed successfully.

• Fill price: $67,455.20
• Quantity: 0.5 BTC
• Total cost: $33,727.60
• Fees: $16.86
• Order ID: ord_123

Portfolio Queries

You: "What's my P&L today?"

AI: Portfolio summary:

• Total value: $52,450
• Unrealized P&L: +$1,230 (+2.4%)
• Realized P&L today: +$340
• Buying power: $15,000

Open positions:

Polymarket Queries

You: "What are the BTC hourly odds?"

AI: Polymarket BTC 1-hour Up/Down market:

• Up probability: 54.5% (price: $0.545)
• Down probability: 45.5% (price: $0.455)
• Time remaining: 47 minutes
• Volume: $25,000 traded this interval
• Liquidity: $12,000

The prediction market is slightly bullish, aligned with the positive OBI (0.12) on exchange orderbooks.

Conditional Orders

You: "Buy 50 SOL if it drops below $140"

AI: I'll set up a conditional buy order:

• Action: Buy 50 SOL/USDT
• Condition: Price drops below $140.00
• Order type: Market (when triggered)
• Estimated cost: ~$7,000

This trigger will be monitored until conditions are met. Note that pending conditional actions expire after 5 minutes for safety.

Multi-Turn Conversations

The AI remembers context within a session (up to 20 messages):

You: "How is SOL looking?"

AI: SOL/USDT at $145.30, up 3.2% in 24h. Strong buying pressure with OBI at 0.22. Volume spike detected (2.8x average). A bid wall at $144 (12,000 SOL, 6x median) is providing support.

You: "Buy 100 of it"

AI: I'll place a market buy order for 100 SOL/USDT at approximately $145.30.

• Estimated cost: $14,530
• Max order limit: $10,000

This order exceeds your maximum order size of $10,000. You can either reduce the quantity or adjust your safety limits.

You: "OK buy 50 instead"

AI: I'll place a market buy order for 50 SOL/USDT at approximately $145.30.

• Estimated cost: $7,265
• Fee estimate: ~$3.63

Please confirm to execute. [Action: act_abc456, expires in 5 minutes]

Safety Rails

Every trade has multiple layers of protection:

Confirmation Required

No trade is ever executed without your explicit confirmation via POST/v1/chat/confirm/:action_id. The AI proposes; you decide.

Action Expiry

Pending actions expire after 5 minutes. This prevents execution under stale market conditions. If an action expires, you need to create a new trade request.

Position Size Limits

Symbol Allowlist

Only symbols that Market.ai actively tracks can be traded. This prevents accidental trades on illiquid or unknown tokens. The default allowed symbols include major pairs like BTC/USDT, ETH/USDT, SOL/USDT, and approximately 25 others.

Double-Execution Prevention

Each action_id is single-use. Attempting to confirm the same action twice returns an error.

Broker Setup (Credentials)

To execute trades, store your exchange API credentials via the /v1/credentials endpoint. Credentials are encrypted with AES-256-GCM before storage. Market.ai never stores plaintext secrets.

Store Credentials

# Binance (key + secret)
curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "binance",
    "label": "My Binance Trading Account",
    "apiKey": "your-binance-api-key",
    "apiSecret": "your-binance-api-secret"
  }' \
  https://api.market-ai.dev/v1/credentials

# OKX (key + secret + passphrase)
curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "okx",
    "label": "OKX Trading",
    "apiKey": "your-okx-key",
    "apiSecret": "your-okx-secret",
    "passphrase": "your-okx-passphrase"
  }' \
  https://api.market-ai.dev/v1/credentials

# Polymarket (wallet + CLOB credentials)
curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "polymarket",
    "label": "Polymarket",
    "walletPrivateKey": "your-wallet-private-key",
    "clobApiKey": "your-clob-api-key",
    "clobApiSecret": "your-clob-api-secret",
    "clobPassphrase": "your-clob-passphrase"
  }' \
  https://api.market-ai.dev/v1/credentials

Required fields by exchange:

List Credentials

Credentials are returned in masked form -- secrets are never exposed.

curl -H "Authorization: Bearer mk_live_abc123..." \
  https://api.market-ai.dev/v1/credentials

Response:

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cred_abc123",
        "exchange": "binance",
        "authType": "key_secret",
        "label": "My Binance Trading Account",
        "maskedKey": "abc...xyz",
        "hasPassphrase": false,
        "hasWalletKey": false,
        "validated": false,
        "createdAt": 1708776300000,
        "updatedAt": 1708776300000
      }
    ],
    "total": 1
  },
  "meta": { "timestamp": 1708776300000 }
}

Test Credentials

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  https://api.market-ai.dev/v1/credentials/cred_abc123/test

Delete Credentials

curl -X DELETE -H "Authorization: Bearer mk_live_abc123..." \
  https://api.market-ai.dev/v1/credentials/cred_abc123

Sessions

Conversations are organized into sessions. Each session maintains:

• Message history -- Up to 20 recent messages are included in the AI's context window
• Pending actions -- Unconfirmed trade proposals
• User context -- Current positions, recent signals for held symbols

Session behavior:

To start a new conversation thread, simply omit the sessionId parameter.

Channel Integrations

Discord Bot

The Market.ai Discord bot allows trading directly from Discord:

• Slash commands: /trade, /portfolio, /market, /polymarket
• Trade confirmations: Button-based confirm/cancel in Discord
• Thread-based sessions: Each Discord thread maps to one chat session
• Embed formatting: Trade proposals and executions displayed as rich embeds

Telegram Bot

The Market.ai Telegram bot allows trading from Telegram:

• Message-based: Type natural language messages to the bot
• Inline keyboard: Confirm/cancel buttons for trade proposals
• Markdown formatting: Market data formatted for readability
• Per-chat sessions: Each Telegram chat is a separate session

Tier Limits

When you exceed the daily message limit:

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Daily chat limit exceeded. Upgrade for higher limits.",
    "retry_after": 3600
  }
}

The counter resets at midnight UTC.