npm package: @marketmotion/sdk
Description: Market Motion SDK — TypeScript client for the Market Motion intelligence API. Search 25K+ entities, scan cross-venue arbitrage, monitor alerts, and access the entity graph programmatically.
Author: Market Motion
Latest version: 1.0.0

# @marketmotion/sdk

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

## Install

```bash
npm install @marketmotion/sdk
```

## Quick Start

```typescript
import { MotionClient } from '@marketmotion/sdk';

const client = new MotionClient({ apiKey: 'your-api-key' });

// Search entities
const results = await client.searchEntities('bitcoin');

// Get entity details + market exposure
const entity = await client.getEntity('bitcoin');

// Cross-venue mispricings
const arbs = await client.getMispricings({ minSpread: 5 });

// Signal feed (injuries, political changes, earnings, etc.)
const signals = await client.getSignalFeed({ limit: 20 });
```

## Configuration

```typescript
// Option 1: Pass directly
const client = new MotionClient({
  apiKey: 'mk_...',
  baseUrl: 'https://api.marketmotion.xyz', // default
});

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

## API Coverage

### Entities
- `searchEntities(query, opts?)` — Full-text entity search
- `getEntity(slug)` — Entity details with markets, attributes, relationships
- `getEntityAttributes(slug)` — Key-value attributes from 22 source connectors
- `getEntityGraph(slug, opts?)` — Relationship graph traversal
- `getEntityRelated(slug, opts?)` — Related entities
- `getEntityNeighborhood(slug, opts?)` — Graph neighborhood

### Markets
- `getCuratedMarkets()` — Staff-curated market picks
- `searchMarkets(query, opts?)` — Market search
- `filterMarkets(opts?)` — Filter by venue, category, status
- `getPredictionMarkets(opts?)` — Polymarket/Kalshi listings
- `getHyperliquidMarkets(opts?)` — Hyperliquid perpetuals
- `getPriceHistory(identifier, opts?)` — OHLCV price history

### Intelligence
- `getEntityISQ(slug, opts?)` — Information Sentiment Quotient scores
- `getEntitySentiment(slug, opts?)` — Sentiment analysis windows
- `getIntelligenceBrief(slug, opts?)` — AI-generated intelligence briefs
- `getEntityRumors(slug, opts?)` — Rumor detection
- `getForecastHistory(slug, opts?)` — AI forecast track record
- `getForecastAccuracy()` — System-wide forecast accuracy

### Cross-Venue
- `getMispricings(opts?)` — Cross-venue spread detection
- `getCrossVenueMarkets(opts?)` — Matched markets across venues
- `getMovers(opts?)` — Biggest price movers

### Alerts & Signals
- `getAlerts(opts?)` — Alert inbox
- `getSignalFeed(opts?)` — Real-time signal feed

### News
- `getTrendingNews(limit?)` — Trending news
- `getEntityNews(slug, opts?)` — Entity-specific news
- `getMarketNews(marketId, opts?)` — Market-specific news
- `getNewsByCategory(category, opts?)` — News by category

### Trading (Polymarket)
- `getPolymarketStatus()` — Account status
- `getPolymarketBalance()` — USDC balance
- `getPolymarketPositions()` — Open positions
- `placePolymarketOrder(params)` — Place order
- `cancelPolymarketOrder(orderId)` — Cancel order
- `getPolymarketOrderbook(tokenId)` — Order book

### Trading (Hyperliquid)
- `placeHyperliquidOrder(params)` — Place perp order
- `closeHyperliquidPosition(orderId)` — Close position

### Webhooks
- `listWebhooks()` — List registered webhooks
- `createWebhook(params)` — Register webhook endpoint
- `deleteWebhook(id)` — Remove webhook
- `getWebhookDeliveries(id, opts?)` — Delivery history

### Account
- `validateKey()` — Validate API key
- `getUserProfile()` — User profile
- `getWatchlist()` — Watchlist items
- `addToWatchlist(type, id, venue?)` — Add to watchlist
- `removeFromWatchlist(type, id)` — Remove from watchlist

## Error Handling

```typescript
import { MotionClient, ApiError } from '@marketmotion/sdk';

try {
  const entity = await client.getEntity('nonexistent');
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status);  // 404
    console.log(error.message); // "Not found"
  }
}
```

## Requirements

- Node.js >= 18 (uses native `fetch`)
- Zero runtime dependencies

## Links

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