# marketmotion

Python SDK for the [Market Motion](https://marketmotion.xyz) intelligence API. Search 25K+ entities, scan cross-venue arbitrage, monitor alerts, and access the entity graph.

## Install

```bash
pip install marketmotion
```

## Quick Start

```python
from marketmotion import MotionClient

client = MotionClient(api_key="mk_...")

# Search entities — returns { "entities": [...], "pagination": {...} }
results = client.search_entities("bitcoin")
for e in results["entities"]:
    print(e["displayName"])

# Get entity with market exposure — returns { "entity": {...}, "markets": [...] }
data = client.get_entity("crypto-l1-btc")
print(f"{data['entity']['displayName']}: {len(data['markets'])} markets")

# Cross-venue arbitrage — returns { "mispricings": [...] }
arbs = client.get_mispricings(min_spread=5)

# Signal feed — returns { "signals": [...], "pagination": {...} }
signals = client.get_signal_feed(limit=20)
for s in signals["signals"]:
    print(s["type"], s["title"])
```

> **Note:** The SDK automatically unwraps the API's `{ success, data }` envelope.
> You get the `data` payload directly — no need to dig into `result["data"]`.

## Configuration

```python
# Option 1: Pass directly
client = MotionClient(api_key="mk_...", base_url="https://api.marketmotion.xyz")

# Option 2: Environment variables
# MOTION_API_KEY=mk_...
# MOTION_API_URL=https://api.marketmotion.xyz
client = MotionClient()
```

## API Coverage

| Category | Methods |
|----------|---------|
| Entities | `search_entities`, `get_entity`, `get_entity_attributes`, `get_entity_graph`, `get_entity_related` |
| Markets | `search_markets`, `filter_markets`, `get_prediction_markets`, `get_hyperliquid_markets`, `get_price_history`, `get_cross_venue_markets` |
| Intelligence | `get_entity_isq`, `get_entity_sentiment`, `get_intelligence_brief`, `get_entity_rumors` |
| Arbitrage | `get_mispricings`, `get_cross_venue_markets`, `get_movers` |
| Alerts | `get_alerts`, `get_signal_feed` |
| News | `get_trending_news`, `get_entity_news`, `get_market_news`, `get_news_by_category` |
| Forecasts | `get_forecast_history`, `get_forecast_accuracy` |
| Trading | `place_polymarket_order`, `place_hyperliquid_order`, `get_positions` |
| Webhooks | `list_webhooks`, `create_webhook`, `delete_webhook` |
| Account | `validate_key`, `get_user_profile`, `get_watchlist` |

## Error Handling

```python
from marketmotion import MotionClient, ApiError

try:
    entity = client.get_entity("nonexistent")
except ApiError as e:
    print(e.status)   # 404
    print(e.body)     # {"success": false, "error": "Entity not found"}
```

## Links

- [API Docs](https://docs.marketmotion.xyz)
- [TypeScript SDK](https://www.npmjs.com/package/@marketmotion/sdk)
- [CLI](https://www.npmjs.com/package/@marketmotion/cli)
- [MCP Server](https://www.npmjs.com/package/@marketmotion/mcp)
