> ## Documentation Index
> Fetch the complete documentation index at: https://motiontrade.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Trading Systems

> Build AI trading agents with structured market context

## The Problem with LLM Trading

Most AI trading systems face a fundamental problem: **context acquisition**.

When an LLM needs to make trading decisions, it typically:

1. Searches the web for information
2. Parses unstructured text
3. Extracts entities and relationships
4. Hopes it didn't hallucinate

This is slow, unreliable, and error-prone.

## Market Motion Solution

One API call gives your AI agent everything it needs—**structured, typed, attributed data**.

```javascript theme={null}
// Instead of: "Search web for Patrick Mahomes injury news"
// Do this:
const entity = await fetch('/api/entities/patrick-mahomes');

// Directly access structured data
const injuryStatus = entity.attributes.injury_status; // "questionable"
const source = entity.attributes.injury_status_source; // "ESPN"
const affectedMarkets = entity.marketExposures; // Array of markets
```

## Architecture Pattern

<Steps>
  <Step title="Entity Discovery">
    Use search or categories to find relevant entities
  </Step>

  <Step title="Context Retrieval">
    Fetch entity details with relationships and market exposures
  </Step>

  <Step title="Signal Detection">
    Monitor attribute changes that signal trading opportunities
  </Step>

  <Step title="Market Mapping">
    Identify which markets are affected by entity changes
  </Step>

  <Step title="Trade Execution">
    Execute trades on Polymarket/Kalshi directly
  </Step>
</Steps>

## Example: Sports Betting Agent

```python theme={null}
import requests

BASE_URL = "https://api.marketmotion.xyz/api"

class SportsAgent:
    def __init__(self, api_key=None):
        self.headers = {"X-API-Key": api_key} if api_key else {}

    def check_injury_opportunities(self, team_slug):
        """Find betting opportunities from injury updates."""

        # Get team entity
        team = requests.get(
            f"{BASE_URL}/entities/{team_slug}",
            headers=self.headers
        ).json()["entity"]

        # Get all players on the team
        players = [
            r["entity"] for r in team.get("relationships", [])
            if r["role"] == "has_player"
        ]

        opportunities = []

        for player_ref in players:
            # Get full player details
            player = requests.get(
                f"{BASE_URL}/entities/{player_ref['slug']}",
                headers=self.headers
            ).json()["entity"]

            injury_status = player.get("attributes", {}).get("injury_status")

            if injury_status in ["questionable", "out"]:
                # This player's status may affect markets
                opportunities.append({
                    "player": player["displayName"],
                    "status": injury_status,
                    "markets": player.get("marketExposures", []),
                    "source": player["attributes"].get("injury_status_source")
                })

        return opportunities

# Usage
agent = SportsAgent(api_key="your_key")
opps = agent.check_injury_opportunities("kansas-city-chiefs")

for opp in opps:
    print(f"{opp['player']} is {opp['status']}")
    print(f"  Source: {opp['source']}")
    print(f"  Affected markets: {len(opp['markets'])}")
```

## Example: Political Event Agent

```python theme={null}
class PoliticsAgent:
    def monitor_approval_ratings(self):
        """Monitor politicians for approval rating changes."""

        # Get all politicians
        response = requests.get(
            f"{BASE_URL}/entities",
            params={"category": "politics", "type": "person", "limit": 100},
            headers=self.headers
        ).json()

        signals = []

        for pol in response["data"]["entities"]:
            attrs = pol.get("attributes", {})
            approval = attrs.get("approval_rating")

            if approval and approval < 40:
                # Low approval - check for election markets
                full_entity = requests.get(
                    f"{BASE_URL}/entities/{pol['slug']}",
                    headers=self.headers
                ).json()["entity"]

                election_markets = [
                    m for m in full_entity.get("marketExposures", [])
                    if "election" in m["market"]["title"].lower()
                ]

                if election_markets:
                    signals.append({
                        "politician": pol["displayName"],
                        "approval": approval,
                        "markets": election_markets
                    })

        return signals
```

## Prompt Engineering with Entity Context

When using LLMs for trading decisions, inject entity context:

```python theme={null}
def build_trading_prompt(entity_slug, question):
    """Build an LLM prompt with full entity context."""

    # Fetch entity
    entity = requests.get(f"{BASE_URL}/entities/{entity_slug}").json()["entity"]

    # Fetch relationship graph
    graph = requests.get(
        f"{BASE_URL}/entities/{entity_slug}/graph",
        params={"depth": 2}
    ).json()["graph"]

    # Build context
    context = f"""
Entity: {entity['displayName']} ({entity['entityType']})
Category: {entity['category']}/{entity.get('subcategory', 'N/A')}

Attributes:
{json.dumps(entity.get('attributes', {}), indent=2)}

Relationships:
{chr(10).join([f"- {r['role']}: {r['entity']['displayName']}" for r in entity.get('relationships', [])])}

Connected Markets ({len(entity.get('marketExposures', []))} total):
{chr(10).join([f"- {m['market']['title']} ({m['market']['venue']})" for m in entity.get('marketExposures', [])[:5]])}

Relationship Graph: {len(graph['nodes'])} nodes, {len(graph['edges'])} edges
"""

    prompt = f"""You are a trading analyst. Given the following entity data, {question}

{context}

Provide your analysis:"""

    return prompt
```

## Best Practices

<AccordionGroup>
  <Accordion title="Cache entity data">
    Entity attributes don't change every second. Cache for 5-15 minutes to reduce API calls and latency.
  </Accordion>

  <Accordion title="Use graph depth wisely">
    Depth 1 is usually enough. Depth 2-3 for complex relationship analysis. More depth = more data to process.
  </Accordion>

  <Accordion title="Trust the source attribution">
    Every attribute includes a source. Use this to weight confidence in your trading decisions.
  </Accordion>

  <Accordion title="Separate context from execution">
    Use Market Motion for context and discovery. Execute trades directly on venue APIs for speed.
  </Accordion>
</AccordionGroup>

## LLM Context File

For AI systems that need comprehensive API documentation, use our machine-readable context file:

```
https://marketmotion.xyz/llms.txt
```

This contains all endpoints, schemas, and examples in a format optimized for LLM consumption.