Skip to content
motion Developers API v1
MCP Pricing Open motion Get a key

motion API · v1 · data + trading

Onchain data and trading, for code and agents.

The launch board, trending coins, token detail, holders, trades, route quotes and perps on Robinhood Chain, BNB Chain, Solana and NEAR: the same data the motion terminal trades on. JSON over HTTPS, and an MCP server your agent plugs straight into.

REST base URLhttps://motion.gift/api/v1
MCP URLhttps://motion.gift/mcp
Quick startConnect an agent
  • 4 chainsRobinhood, BNB, Solana, NEAR
  • 9 readsREST, plus your usage
  • MCPnine reads + swap_quote
  • 0.1% swapsRobinhood, BNB, Solana

Quick start

Your first call in 30 seconds

  1. Get a key

    Keys are issued by motion on request; there is no self-serve signup yet. Ask for one. You get a key that starts with msk_, one per app or agent.

  2. Put it in your environment

    Keep it out of your code and out of any URL.

  3. Call an endpoint

    The two coins trending on Robinhood Chain right now. Every answer has the same envelope: ok, data, meta.

  4. Go deeper

    Take a rows[].address and ask /token, /holders or /quote about it.

shell
export MOTION_API_KEY="msk_…"
Request
curl -s "https://motion.gift/api/v1/trending?chain=robinhood&limit=2" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response, trimmed
{
  "ok": true,
  "data": {
    "source": "alpha",
    "at": "2026-10-28T11:12:00.433Z",
    "rows": [
      {
        "rank": 1,
        "address": "0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
        "symbol": "LIME",
        "name": "Lime Cat",
        "launchpad": "Pons V2",
        "stage": "migrated",
        "priceUsd": 0.000184213,
        "mcapUsd": 184213.5,
        "volume24hUsd": 612840.9,
        "change1hPct": 12.37,
        "holders": 1287,
        "url": "https://motion.gift/token/0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
        "signals": { "motionRank": 3, "smartWallets": 7 }
      },
      {
        "rank": 2,
        "address": "0x2b7e90c4d1a6f35e8b0c9d2f7a4e1b6c3d5f8a09",
        "symbol": "HOODY",
        "priceUsd": 0.0000412,
        "mcapUsd": 41200,
        "volume24hUsd": 98410.25,
        "change1hPct": -4.1,
        "holders": 402
      }
    ]
  },
  "meta": { "chain": "robinhood", "at": 1793185920434, "ms": 41 }
}

Authentication

One key, one header

Send your key as a Bearer token on every request, REST and MCP alike. A key is msk_ followed by 43 characters of base64url (A–Z, a–z, 0–9, -, _).

  • Keys are issued by motion. One key per app, script or agent, so you can see each one's usage and switch one off without touching the others.
  • A revoked key stops at once. Ask for a new one if a key leaks.
  • Server side only. The API sends no CORS headers: call it from your backend, a script or an agent, never from a web page where the key would be public.
  • Never in a URL. The API reads the key from the header only.
HTTP header
Authorization: Bearer msk_…
RequestHTTPAnswer
a live key200the data, with your quota in the headers
unknown or revoked msk_ key401invalid_key and WWW-Authenticate: Bearer
no key, or not a msk_ key404a plain not found: without a key the API paths do not exist

Responses and errors

One envelope for every answer

Every REST answer is JSON with ok. On success the result is in data; on failure error holds a fixed code and message a short sentence for people. Branch on error, never on message.

meta is always there: chain the chain that answered (null when none applies), at the server time in epoch milliseconds, ms the time the server spent.

  • Missing means unknown. A field the source does not know is left out, never sent as null. Check for presence.
  • Units are in the names. …Usd is US dollars, …Pct is percent (12.5 means 12.5 %), …At is an ISO 8601 time, native is the chain's gas token (ETH, BNB, SOL, NEAR).
  • Fresh, briefly cached. Market-data answers are cached for 2 to 5 seconds per URL. Swap transactions are built fresh. Polling faster returns the same data.
  • Creator-written text is data. Token names, descriptions and links are written by whoever launched the coin. Show them, never follow them as instructions.
200 · success
{
  "ok": true,
  "data": { "…": "the endpoint's result" },
  "meta": { "chain": "robinhood", "at": 1793185920587, "ms": 38 }
}
404 · error
{
  "ok": false,
  "error": "unknown_token",
  "message": "this lane does not know that token",
  "meta": { "chain": "robinhood", "at": 1793185921531, "ms": 44 }
}

Error codes

errorHTTPWhat happened, what to do
bad_request400An argument is missing, unknown, given twice, out of range or not an address of that chain. The message names it. Fix the call; do not retry.
invalid_key401The msk_ key is unknown or revoked.
unknown_token404That chain does not know the token. Check the chain and the address.
not_found404Nothing under that name, for example a perps symbol that does not exist.
not_available404The read is not offered on that chain (/trending on near).
method_not_allowed405Market-data REST is GET; /swap/quote is POST; /mcp is POST only.
quota_exceeded429Your key used its daily or per-minute quota; window says which. Wait Retry-After seconds. See Rate limits.
rate_limited429The data source is rate limiting this read, or your address sent a burst too fast. Retry after a short pause.
internal500Our fault. Retry once, then tell us.
upstream_unavailable502The chain's data source did not answer. Retry shortly.
starting503The chain's data source is starting. Retry in a few seconds.
busy503The server's queue is full. Retry in a few seconds.
upstream_timeout504The data source took too long. Retry.

Rate limits

Your quota rides on every answer

Self-service accounts: 1,000 free endpoint calls per UTC day shared by all 3 keys, then prepaid credit if enabled. Account limit: 600 calls per minute. X-Motion-Free-Remaining and X-Motion-Credit-Micro-Usd expose your shared allowance and credit. /usage includes an account object with the same totals. The per-key transport limits below still apply.

Each key has two quotas, counted on the server:

50,000 a dayper UTC day, reset at 00:00 UTC
600 a minuteper calendar minute
  • What counts. Every REST call is one request, errors included. On /mcp each tools/call in a POST is one request; a POST without one is one.
  • What does not. GET /usage and GET /swap/trades do not consume the request quota; edge rate limits still apply.
  • Over a limit you get 429 quota_exceeded with Retry-After. Wait that long; do not retry in a loop.
  • Per address, at the edge, bursts are also limited. That 429 is {"ok":false,"error":"rate_limited","retryAfter":10} with Retry-After: 10.
  • Need more? Limits are set per key. Ask us.
HeaderMeaning
X-RateLimit-Limitrequests per UTC day for this key
X-RateLimit-Remainingwhat is left of today
X-RateLimit-Resetepoch seconds of the next 00:00 UTC
X-RateLimit-Limit-Minuterequests per minute for this key
X-RateLimit-Remaining-Minutewhat is left of this minute
Retry-Afteron a 429 only: seconds to wait
429 · quota_exceeded
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 31877
X-RateLimit-Reset: 1793232000
X-RateLimit-Limit-Minute: 600
X-RateLimit-Remaining-Minute: 0

{
  "ok": false,
  "error": "quota_exceeded",
  "window": "minute",
  "message": "the per-minute limit of this key is reached — try again after Retry-After seconds",
  "meta": { "chain": null, "at": 1793185921623, "ms": 0 }
}

Chains

Four chains, one parameter

Pass chain on every token read. It defaults to robinhood. Aliases work too: rh and hood, bnb, solana.

chainNetwork, venues, token address
robinhoodRobinhood Chain · native ETH · Pons V2, Varo and the Uniswap poolsan EVM address: 0x and 40 hex characters (any case)
bscBNB Chain · native BNB · four.meme, Flap, genius.fun and PancakeSwapan EVM address: 0x and 40 hex characters
solSolana · native SOL · Pump.fun, PumpSwap and Jupiter routesthe mint, base58, 32 to 44 characters (case-sensitive)
nearNEAR · native NEAR · nearly and Rheathe token's account id, for example token.example.near. /trending is not available on near.
Perps are chainless: /perps/markets and /perps/market read Lighter's Robinhood Chain instance (public data), so their meta.chain is robinhood.

Endpoints

Nine reads and your usage

All GET, all under https://motion.gift/api/v1, arguments in the query string. An argument the endpoint does not take is a 400, so a typo never passes silently.

GET/trendingTokens trending on one chain now GET/boardThe live launch board by lane GET/tokenOne token: market, holders, socials, route GET/holdersTop holders with share and tags GET/tradesThe most recent trades GET/searchFind tokens on one chain or all four GET/quoteVenue and price impact, no transaction GET/perps/marketsEvery Lighter perps market GET/perps/marketOne perps market in detail GET/usageYour own quota and counters, free

The token row

/trending, /board and /search list tokens as rows of these fields, and /token starts with them. Any field may be missing when it is not known.

address
the token address on its chain (EVM in lower case)
symbol, name
as the creator wrote them
launchpad, stage
where it launched (Pons V2, four.meme, Pump.fun …) and where it is now: new, graduating or migrated
priceUsd, mcapUsd
price and market cap in USD
liquidityUsd, volume24hUsd
pool liquidity and 24 hour volume in USD
change5mPct, change1hPct, change24hPct
price change in percent
trades, holders
trade count and holder count
progressPct
bonding-curve progress in percent, only before it graduates
taxPct
estimated fee in percent for the displayed market, not a universal token transfer tax. Hook fees can differ between pools; this is not a guaranteed execution fee
taxMarketId · markets
/token identifies the displayed market with taxMarketId and lists liquid, tradeable markets with their own taxPct, taxLivePct, hook and depth. route.marketId identifies the reference route market. Missing fee values mean unknown, not zero. Dynamic fees and execution prices can change.
Multiple pools
A token can have a 5% Pons hook pool (1% base fee + 4% creator fee) and a separate 1% V3 pool. Read the matching market fee; do not apply the hook fee to every route. Bridge fees, price impact and Motion execution fees are separate.
ageSeconds
seconds since launch
quote
the quote token's symbol, only when it is not the chain's native token
url
the token's page on motion.gift
GET

/board

market data · $0.001 a call

The live launch board of one chain, one lane at a time, as motion.gift shows it: new launches, coins about to graduate from their curve, and coins that migrated to a pool. Returns lane, nativeUsd (the native token's USD price) and token rows.

chain
robinhood, bsc, sol or neardefault robinhood
lane
new, graduating or migrateddefault new
limit
rows, 1 to 80default 20
Request
curl -s "https://motion.gift/api/v1/board?chain=sol&lane=new&limit=2" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response, trimmed
{
  "ok": true,
  "data": {
    "lane": "new",
    "nativeUsd": 187.42,
    "rows": [
      {
        "address": "9pQmF3vT6uK2cWd8hLs4bYxRj7NaE5gZoV1tMiH3pump",
        "symbol": "GLASS",
        "name": "Glass Frog",
        "launchpad": "Pump.fun",
        "stage": "new",
        "priceUsd": 0.00000612,
        "mcapUsd": 6120.4,
        "volume24hUsd": 14802.11,
        "change5mPct": 38.2,
        "trades": 214,
        "holders": 61,
        "progressPct": 22.8,
        "ageSeconds": 95,
        "url": "https://motion.gift/sol/token/9pQmF3vT6uK2cWd8hLs4bYxRj7NaE5gZoV1tMiH3pump"
      },
      {
        "address": "5hVwZk3NqT8sYcRb2mLx7AeU4gDp9FjK6oWt1nCy8pump",
        "symbol": "MOSS",
        "launchpad": "Pump.fun",
        "stage": "new",
        "priceUsd": 0.00000411,
        "mcapUsd": 4110,
        "progressPct": 9.1,
        "ageSeconds": 41
      }
    ]
  },
  "meta": { "chain": "sol", "at": 1793185912377, "ms": 12 }
}
GET

/token

market data · $0.001 a call

One token in full: the token row plus everything the token page knows.

chain
robinhood, bsc, sol or neardefault robinhood
addressrequired
the token address of that chain (see Chains)

Beyond the token row

athMcapUsd
the highest market cap seen
buys, sells
trade counts by side
top10Pct, devPct, snipersPct
supply held by the top 10, the deployer, snipers (percent)
graduated, tradeable
off its curve; tradeable now
pair
quote symbol and, for a non-native quote, quoteUsd
deployer, createdAt, migratedAt, priceAt
who made it, when; when the price was read
socials, description, image
x, website, telegram, discord, xFollowers. Creator-written.
route
the pool motion's router picks: pool, depthUsd and priceImpactAt, a reference ladder of { native, impactPct }
Request
curl -s "https://motion.gift/api/v1/token?chain=robinhood&address=0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response
{
  "ok": true,
  "data": {
    "address": "0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
    "symbol": "LIME",
    "name": "Lime Cat",
    "launchpad": "Pons V2",
    "stage": "migrated",
    "priceUsd": 0.000184213,
    "mcapUsd": 184213.5,
    "liquidityUsd": 41250.12,
    "volume24hUsd": 612840.9,
    "change5mPct": 1.84,
    "change1hPct": 12.37,
    "change24hPct": 148.2,
    "trades": 3412,
    "holders": 1287,
    "taxPct": 1,
    "ageSeconds": 52140,
    "url": "https://motion.gift/token/0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
    "athMcapUsd": 251904.33,
    "buys": 2105,
    "sells": 1307,
    "top10Pct": 28.4,
    "devPct": 1.2,
    "snipersPct": 3.6,
    "graduated": true,
    "tradeable": true,
    "source": "pons",
    "nativeUsd": 3912.4,
    "pair": { "quote": "ETH" },
    "deployer": "0x51d0b7e93c2a48f6e1b5a9c07d3e8f2a6b4c1d90",
    "createdAt": "2026-10-27T20:43:12.000Z",
    "migratedAt": "2026-10-27T22:10:05.000Z",
    "priceAt": "2026-10-28T11:11:58.412Z",
    "socials": { "website": "https://limecat.example" },
    "description": "A cat that only eats limes.",
    "route": {
      "pool": "v4",
      "depthUsd": 20480.55,
      "priceImpactAt": [
        { "native": 0.01, "impactPct": 1.12 },
        { "native": 0.1, "impactPct": 1.9 },
        { "native": 1, "impactPct": 9.4 }
      ]
    }
  },
  "meta": { "chain": "robinhood", "at": 1793185920587, "ms": 38 }
}
GET

/holders

holders · $0.005 a call

The top holders of a token with their share of supply and tags (pool, curve, dev …), plus the holder count and the top 10 share. Pools, curves, lockers and the burn address are tagged and kept out of holders and top10Pct.

partial: true means a scan of a busy older coin is still running: ask again in a moment for the full list.

chain
robinhood, bsc, sol or neardefault robinhood
addressrequired
the token address
limit
rows, 1 to 100default 20
Request
curl -s "https://motion.gift/api/v1/holders?chain=robinhood&address=0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215&limit=3" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response
{
  "ok": true,
  "data": {
    "address": "0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
    "holders": 1287,
    "top10Pct": 28.4,
    "devPct": 1.2,
    "snipersPct": 3.6,
    "at": "2026-10-28T11:11:40.000Z",
    "rows": [
      { "address": "0x3c6a9d2f5b8e1c4a7d0f3b6e9c2a5d8f1b4e7a03", "pct": 21.3071, "amount": 213071000, "tags": ["pool"] },
      { "address": "0x7e4b1a9c2d5f80e36b1c4a7d9e2f5b8c0a3d6e19", "pct": 4.0215, "amount": 40215000, "tags": [] },
      { "address": "0x51d0b7e93c2a48f6e1b5a9c07d3e8f2a6b4c1d90", "pct": 1.2, "amount": 12000000, "tags": ["dev"] }
    ]
  },
  "meta": { "chain": "robinhood", "at": 1793185920711, "ms": 64 }
}
GET

/trades

market data · $0.001 a call

The most recent trades of a token, newest first. Each row: at, side (buy or sell), trader, usd, tokens, priceUsd, quoteAmount (in the pair's quote token), tx and tags.

chain
robinhood, bsc, sol or neardefault robinhood
addressrequired
the token address
limit
rows, 1 to 100default 20
Request
curl -s "https://motion.gift/api/v1/trades?chain=robinhood&address=0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215&limit=2" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response
{
  "ok": true,
  "data": {
    "address": "0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
    "symbol": "LIME",
    "quote": "ETH",
    "rows": [
      {
        "at": "2026-10-28T11:11:56.586Z",
        "side": "buy",
        "trader": "0x7e4b1a9c2d5f80e36b1c4a7d9e2f5b8c0a3d6e19",
        "usd": 120.5,
        "tokens": 654133,
        "priceUsd": 0.000184213,
        "quoteAmount": 0.0307995,
        "tx": "0x3e8a1f6c9b2d47e05a8c3f1b6d9e2a7c4f0b5d8e1a3c6f9b2d4e7a0c5f8b1d3e",
        "tags": []
      },
      {
        "at": "2026-10-28T11:11:31.102Z",
        "side": "sell",
        "trader": "0x9b2c5e8f1a4d7b0c3e6f9a2d5b8c1e4f7a0d3b62",
        "usd": 48.12,
        "tokens": 262200,
        "priceUsd": 0.000183527,
        "quoteAmount": 0.0122993,
        "tx": "0xa71c4e9f2b5d80c3e6a9f1b4d7c0e3a6f9b2d5c8e1f4a7b0d3c6e9f2a5b8c1d4",
        "tags": ["sniper"]
      }
    ]
  },
  "meta": { "chain": "robinhood", "at": 1793185920768, "ms": 9 }
}
GET

/quote

route quote · $0.0025 a call

A read-only route quote: the venue motion's router picks for this token (v4, pons, four, flap …), its stage (curve or pool) and pair, the number of hops, the reference price-impact ladder and, with amountUsd, an impact estimate for that size. No transaction, no calldata, nothing to sign.

route is ok, none (no route for this token) or unavailable (the router did not answer; the rest is still filled). The estimate's basis says where it comes from: the router's reference quotes, or pool liquidity when there are none (tax included); extrapolated: true means the size is past the ladder.

chain
robinhood, bsc, sol or neardefault robinhood
addressrequired
the token address
side
buy or selldefault buy
amountUsd
trade size in USD, above 0 and up to 1,000,000: adds the estimateoptional

A buy estimate has spendNative, tokensOut and valueOutUsd; a sell has tokensIn, nativeOut and usdOut.

Request
curl -s "https://motion.gift/api/v1/quote?chain=robinhood&address=0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215&side=buy&amountUsd=250" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response
{
  "ok": true,
  "data": {
    "address": "0x8c1f4d2a6b9e03c7d5a1f8e2b4c6d9a0e3f7b215",
    "symbol": "LIME",
    "side": "buy",
    "route": "ok",
    "venue": "v4",
    "stage": "pool",
    "pair": "ETH",
    "hops": 0,
    "tradeable": true,
    "priceUsd": 0.000184213,
    "nativeUsd": 3912.4,
    "taxPct": 1,
    "priceImpactAt": [
      { "native": 0.01, "impactPct": 1.12 },
      { "native": 0.1, "impactPct": 1.9 },
      { "native": 1, "impactPct": 9.4 }
    ],
    "estimate": {
      "amountUsd": 250,
      "priceImpactPct": 1.75,
      "basis": "router reference quotes",
      "spendNative": 0.0638994,
      "tokensOut": 1333400,
      "valueOutUsd": 245.63
    }
  },
  "meta": { "chain": "robinhood", "at": 1793185921204, "ms": 69 }
}
GET

/perps/markets

market data · $0.001 a call

Every perpetual futures market on Lighter (its Robinhood Chain instance, public data), by 24 hour volume: price, mark, 24 hour change and volume, open interest, funding and maximum leverage. live is true while the feed streams.

category
filter, for example crypto or stocksoptional
limit
rows, 1 to 200default 50
Request
curl -s "https://motion.gift/api/v1/perps/markets?category=crypto&limit=2" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response
{
  "ok": true,
  "data": {
    "venue": "lighter",
    "at": "2026-10-28T11:12:01.329Z",
    "live": true,
    "rows": [
      {
        "symbol": "BTC",
        "name": "Bitcoin",
        "category": "crypto",
        "status": "active",
        "priceUsd": 68012.4,
        "markUsd": 68015.1,
        "change24hPct": 1.42,
        "volume24hUsd": 512340112.5,
        "openInterestUsd": 88120440.2,
        "fundingPct": 0.0042,
        "maxLeverage": 50
      },
      {
        "symbol": "ETH",
        "name": "Ethereum",
        "category": "crypto",
        "status": "active",
        "priceUsd": 3912.4,
        "markUsd": 3912.9,
        "change24hPct": -0.38,
        "volume24hUsd": 201554980.1,
        "openInterestUsd": 40211670.4,
        "fundingPct": 0.0031,
        "maxLeverage": 50
      }
    ]
  },
  "meta": { "chain": "robinhood", "at": 1793185921329, "ms": 70 }
}
GET

/perps/market

market data · $0.001 a call

One Lighter perps market by symbol: price, mark and index, best bid and ask, the 24 hour range and volume, open interest, current and next funding, taker and maker fees and the leverage limit. An unknown symbol is 404 not_found.

symbolrequired
letters and digits, for example BTC (any case)
Request
curl -s "https://motion.gift/api/v1/perps/market?symbol=BTC" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response
{
  "ok": true,
  "data": {
    "venue": "lighter",
    "at": "2026-10-28T11:12:01.471Z",
    "live": true,
    "symbol": "BTC",
    "name": "Bitcoin",
    "category": "crypto",
    "status": "active",
    "priceUsd": 68012.4,
    "markUsd": 68015.1,
    "indexUsd": 68009.8,
    "bestBid": 68011.9,
    "bestAsk": 68012.6,
    "high24h": 68840,
    "low24h": 66702.5,
    "change24hPct": 1.42,
    "volume24hUsd": 512340112.5,
    "openInterestUsd": 88120440.2,
    "fundingPct": 0.0042,
    "nextFundingPct": 0.0038,
    "fundingAt": "2026-10-28T12:00:00.000Z",
    "maxLeverage": 50,
    "takerFeePct": 0.02,
    "makerFeePct": 0
  },
  "meta": { "chain": "robinhood", "at": 1793185921471, "ms": 85 }
}
GET

/usage

free · not counted

Your key's own numbers: used today, the daily limit and what is left, when it resets, this minute, all-time total, refusals, MCP calls, per-endpoint counts with server latency (p50 / p95), and the last 24 hours by hour. Free: it is not counted and never refused by the quota. It takes no arguments.

Endpoint names in endpoints are the REST names; mcp:token and the like are MCP tool calls.

Request
curl -s "https://motion.gift/api/v1/usage" \
  -H "Authorization: Bearer $MOTION_API_KEY"
200 · response, trimmed
{
  "ok": true,
  "data": {
    "key": { "id": "7c3e9a21b4f05d68", "identified": true },
    "day": {
      "date": "2026-10-28",
      "used": 2022,
      "limit": 50000,
      "remaining": 47978,
      "resetAt": "2026-10-29T00:00:00.000Z",
      "resetInSeconds": 46079
    },
    "minute": { "used": 12, "limit": 600, "remaining": 588, "resetInSeconds": 59 },
    "total": 5116,
    "firstAt": "2026-10-27T11:40:00.299Z",
    "lastAt": "2026-10-28T11:12:01.550Z",
    "throttled": { "today": 0, "total": 0 },
    "mcp": { "today": 455, "total": 1161 },
    "endpoints": [
      { "name": "board", "today": 423, "total": 1068, "p50Ms": 115, "p95Ms": 193 },
      { "name": "mcp:token", "today": 108, "total": 306, "p50Ms": null, "p95Ms": null }
    ],
    "hours": [
      { "at": "2026-10-28T10:00:00.000Z", "n": 79 },
      { "at": "2026-10-28T11:00:00.000Z", "n": 13 }
    ],
    "latency": { "p50Ms": 120, "p95Ms": 196, "samples": 577 },
    "free": ["usage"]
  },
  "meta": { "chain": null, "at": 1793185921623, "ms": 1 }
}
POST

/swap/quote

execution · 0.1% per completed swap

Build an unsigned buy or sell on Robinhood, BNB or Solana using a managed msk_ key. Your wallet signs and submits the returned transaction. The API never receives your wallet key. NEAR and perpetuals execution are not supported.

GET /quote is a market estimate. POST /swap/quote builds transaction bytes and checks them by simulation. A successful quote is not a completed trade.

chain
robinhood, bsc or sol
address
token contract or Solana mint
side
buy or sell
amount
positive integer string: wei / lamports for buys, token base units for sells. Never a floating-point amount.
trader
public wallet address that will sign
recipient
optional; defaults to trader. Solana requires trader.
slippageBps
integer 1–3000; default 100 (1%)

Quote, inspect, sign, confirm

  1. Read /swap/status and request a fresh quote.
  2. Check the network, recipient, fees, minimum output and expiry. EVM simulation may use a funded balance override: verify the wallet can cover input and gas.
  3. For EVM, confirm any exact-amount approvals first, then request a new quote. stage: approval_required is not a swap. Submit the returned transaction through your wallet.
  4. For Solana, deserialize transaction.serialized as a base64 versioned transaction and have the trader sign those exact bytes.
  5. Track the transaction hash/signature to finality. An unknown submission result must be reconciled before any new trade is signed.
Request · 0.0001 BNB → USDT
curl -sS https://motion.gift/api/v1/swap/quote \
  -H "Authorization: Bearer $MOTION_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"chain\":\"bsc\",\"address\":\"0x55d398326f99059ff775485246999027b3197955\",\"side\":\"buy\",\"amount\":\"100000000000000\",\"trader\":\"$TRADER_ADDRESS\",\"slippageBps\":100}"
JavaScript · request only
const response = await fetch("https://motion.gift/api/v1/swap/quote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOTION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chain: "sol",
    address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    side: "buy",
    amount: "1000000", // 0.001 SOL; gas and rent are additional
    trader: process.env.TRADER_ADDRESS,
    slippageBps: 100,
  }),
});
const body = await response.json();
if (!body.ok) throw new Error(body.error);
console.log(body.data); // inspect, then pass to your wallet

What comes back

The usual ok / data / meta envelope. EVM returns transaction (chainId, to, data, value, gas), approvals, fees, minOut, expiresAt and simulation. Solana returns the serialized transaction, recentBlockhash, lastValidBlockHeight, fees, output and simulation details including rent.

EVM quotes expire on-chain after 30 seconds. Solana's 30-second quote freshness is checked by the API; on-chain expiry follows lastValidBlockHeight, not a strict 30-second deadline. Request another quote after expiry.

Errors

Solana size limits return 422 size_cap; EVM oversize input currently returns 400 bad_request. Other rejections include 422 simulation_failed, unsafe_route or unsupported_route: no transaction submitted. 409 quote_expired: requote. 403 forbidden: managed key required. 503 busy: wait before retrying the quote. Quota and provider limits return 429.

Fees and launch limits

Motion charges 10 bps (0.1%) atomically with a successful swap. EVM collects native ETH / BNB from buy input or sell output. Solana collects WSOL inside the Jupiter swap into the treasury token account. Network gas, Solana account rent and venue fees are separate. A quote alone transfers no funds.

Robinhood · 4663
0.01 ETH maximum native size per trade
BNB · 56
0.05 BNB maximum native size per trade
Solana
0.25 SOL maximum native size per trade

Launch caps as of 28 October 2026; they can change. EVM caps are enforced by the router. Solana caps are enforced during quote construction and simulation. Sell limits apply to gross native proceeds. Trading requests share your key quota; the quote service also allows up to 2 concurrent builds per key and 8 in total.

EVM builders can have an owner-configured markup up to 3%, reported separately in builderFeeBps. It cannot be supplied in a request. Solana currently supports only Motion's 10 bps, without builder markup. Token-transfer taxes and unsupported routes can fail simulation; support for a network does not guarantee every token is tradable.

Receipts and attribution

/usage counts API requests and latency, including failed quotes. It is not a settlement or revenue ledger. On EVM, read the router's Executed receipt event for trader, builderId, nonce, input/output and actual motionFee / builderFee. On Solana, verify a finalized successful transaction and its fee-account token balance delta. Failed swaps do not collect the swap fee, but network fees may still be charged.

EVM fee recipient
0x55d678549C86Ea3C2D240b5fa996fC4c5D557c95
Robinhood router
0x5D4A5d6fA0dabd5999C99857998DDEe889B881C0
BNB router
0xC1C0F9d3DED1b7b02C3aB9429CE53164e30b3296
Solana treasury
5ZtmhRo4q9DAtfV7Ccm7yEZWgcJmW33N43gWD5BRWMKx
Solana WSOL fee account
HBr73JAydiS6Y4wpAFGbNK7hQee9Ff4Gm9WGe7MSJwVH

EVM routers updated on 28 October 2026 to use a fresh, isolated EIP-1167 executor per trade. Always use the router and approval spender returned by a fresh quote: approvals for the previous router do not authorize the new one. Historical receipts from both versions remain in the execution ledger.

MCP

Call swap_quote through POST /mcp with the same arguments. It returns the REST envelope as structuredContent and JSON text. The tool builds an unsigned transaction; it never signs or broadcasts.

MCP · tools/call request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "swap_quote",
    "arguments": {
      "chain": "bsc",
      "address": "0x55d398326f99059ff775485246999027b3197955",
      "side": "buy",
      "amount": "100000000000000",
      "trader": "YOUR_PUBLIC_EVM_ADDRESS",
      "slippageBps": 100
    }
  }
}
GET

/swap/status

Requires a managed key and consumes one quota request. Returns enabled, configuredChains, configurationValid, motionFeeBps, your builderFeeBps and submitsTransactions: false. This is configuration availability, not a guarantee that a particular route will succeed.

Request
curl -sS https://motion.gift/api/v1/swap/status \
  -H "Authorization: Bearer $MOTION_API_KEY"
GET

/swap/trades

free · finalized receipts

Your managed key's confirmed executions, realized fees and native trading volume. The server reconciles finalized on-chain receipts automatically; a successful quote alone never increments these totals.

confirmedTrades is the count; chains contains per-network motionFee, builderFee and nativeVolume as exact integer strings, with decimals and feeAsset. ETH / BNB use 18 decimals; WSOL uses 9. No estimated USD revenue is shown.

trades contains transaction hashes, actual amounts, fees and attribution. EVM uses the router's authenticated builderId. Solana uses the exact message hash saved before the unsigned quote was returned. Unmatched transfers to the Solana fee account are not counted as trading commissions.

coverage reports each chain as catching_up, synced, error or reorg_detected, with checkpoint times. stale: true means the totals are incomplete or not current. A sync failure preserves the checkpoint and existing records; it never substitutes zero income. Scanning runs in the background, so newly finalized transactions may appear after a short delay.

Native volume is based on actual settled amounts, excluding gas and account rent. volumeKnownTrades states how many trades have sufficient receipt data for volume. Fees can be known even when volume cannot be derived. at on a record is when it was added to the journal.

Your execution history
curl -sS "https://motion.gift/api/v1/swap/trades?limit=50" \
  -H "Authorization: Bearer $MOTION_API_KEY"
limit
1–100 records; default 50
before
optional opaque nextCursor from the previous response, URL-encoded

Pagination changes the returned rows, not the totals. A key can read only its own executions; an id parameter cannot select another key. The owner's private API dashboard also shows aggregate income and unattributed receipts.

503 not_available means the accounting journal is unavailable, not that no trades occurred. Keep the last known report marked stale and retry later.

MCP

Plug it into your agent

An MCP server at https://motion.gift/mcp, Streamable HTTP. Nine market-data tools and swap_quote for unsigned transactions, typed with JSON Schema, behind the same managed key.

terminal
claude mcp add --transport http motion https://motion.gift/mcp \
  --header "Authorization: Bearer $MOTION_API_KEY"

Run once with MOTION_API_KEY set in your shell; /mcp inside Claude Code shows the ten tools.

Tools

ToolSame as
perps_marketsGET /perps/markets
perps_marketGET /perps/market

The protocol

  • JSON-RPC 2.0 over POST with Content-Type: application/json: initialize, ping, tools/list, tools/call. No sessions and no server stream.
  • Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05. The MCP-Protocol-Version header is optional; any other version is refused.
  • Batches of 1 to 10 messages. Each tools/call counts as one request against your quota.
  • Results carry the REST envelope twice: as JSON text in content[0].text and as structuredContent. isError is true when ok is false.
  • Over quota: HTTP 429 and the JSON-RPC error -32000 with data.error quota_exceeded.
200 · tools/call result, trimmed
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"ok\":true,\"data\":{\"source\":\"alpha\",\"rows\":[…]},\"meta\":{…}}" }
    ],
    "structuredContent": {
      "ok": true,
      "data": {
        "source": "alpha",
        "at": "2026-10-28T11:12:00.433Z",
        "rows": [
          { "rank": 1, "symbol": "LIME", "priceUsd": 0.000184213, "mcapUsd": 184213.5 }
        ]
      },
      "meta": { "chain": "robinhood", "at": 1793185921654, "ms": 0 }
    },
    "isError": false
  }
}

Pricing

Pay per call

Create API key

Start with 1,000 free calls per account per UTC day. Then pay from your Motion API credit, or through Raeto when its merchant connection is enabled. A REST read and the MCP tool that makes the same read are the same call.

Market data

$0.001a call

$1 per 1,000 calls

board, trending, token, trades, search, perps/markets, perps/market

Route quotes

$0.0025a call

$2.50 per 1,000 calls

quote

Holders

$0.005a call

$5 per 1,000 calls

holders

Trading has a separate 0.1% on-chain execution fee. The read-only /quote price above is not a trading commission. Swap quotes consume the shared free allowance, then cost $0.0025 per successful quote. Swap status is free. Obtaining a quote does not collect the on-chain execution fee.

Free: /usage and /swap/trades. Create up to 3 keys in the developer console. All keys share the free account allowance. Paid calls are off until you enable them; failed paid calls are refunded. No negative balance or automatic wallet charge.

Two ways to pay

Motion credit & Raeto Pay

For direct access, top up with USDG on Robinhood Chain in the developer console. A finalized direct token transfer plus a message signed by its sender adds credit once. The console shows the exact token and treasury addresses. Credit is prepaid API service credit, not a withdrawable wallet balance. Use a wallet capable of signing messages; exchange withdrawals and smart-contract wallets are not supported.

Raeto uses separate endpoints: https://motion.gift/api/pay/{endpoint} for the nine market-data and read-only route-quote endpoints above. GET accepts query parameters; POST accepts the same arguments as JSON, for Raeto's MCP tool discovery. No Motion API key is needed.

When connected, an unpaid call returns HTTP 402 with raeto.payTo, amountUsd, resource and payUrl. Pay through Raeto, then retry the identical request with X-Raeto-Receipt. A receipt is bound to that endpoint and its arguments. Success captures payment; failure releases it. Pending merchant configuration returns 503 and collects nothing; the console shows connection status.

Trading quotes are also available through POST /api/pay/swap/quote with JSON arguments and a verified Raeto receipt: $0.0025 per successful quote, plus the usual 0.1% Motion fee only when the swap executes on-chain. The response contains an unsigned transaction; your wallet must inspect, sign and submit it. Raeto controls availability in its marketplace after testing the signing flow. MCP payment receipts do not grant access to private account data, keys or trade history.

Raeto pricing handshake · no key
curl 'https://motion.gift/api/pay/trending?chain=robinhood'

A payment verification timeout is an unknown payment state. Check it in Raeto before paying again. Raeto Pay documentation ↗

Get a key

Create your API key

Start building now

Sign in with your Motion account or create one. Get a key immediately, inspect usage, revoke keys and top up API credit in your own console.

Create API key

Need help?

nick@motion.gift