NEAR Terminal API v1
● v1 · free

Build on every token on NEAR

The NEAR Terminal API gives you the same realtime data that powers nearterminal.tech: every trade on every DEX, candles, holders, top traders, new deploys from every launchpad, trending, wallet analytics and copy-trade leaderboards — plus swap quotes that return ready-to-sign transactions.

Indexed from our own NEAR node, block by block. Typical data delay: about two seconds after a block.

Base URL

What you can build

  • Sniper and alert bots — react to token.created from every launchpad and to trending entries within seconds.
  • Trading bots — get a route and the exact transactions to sign, with slippage protection, from one call.
  • Copy-trading tools — rank wallets with the leaderboard, study a wallet's every position, follow its trades live.
  • Dashboards and charts — candles from 1 second to 1 month, holders, top traders, early buyers, dev activity.
  • Telegram / Discord bots — token cards with price, market cap, tax, risk flags and a link to the chart.

Quickstart#

  1. Get an API key — freeLog in with your NEAR wallet under Get an API key and press Create key. A key looks like nt_live_… and is shown once.
  2. Keep it in an environment variableNever commit it or ship it in a web page.
  3. Make a request
  4. Read the responseEvery success is a JSON object with data (an object or a list) and, for lists, meta (counts, the options you used, the next cursor). Every error has the same shape.

Get an API key#

Free for everyone: log in with your NEAR wallet and create up to 3 keys, each with 60 requests per minute. Name each key after what uses it, so you can revoke one without touching the others.

Loading…

Logging in signs a message with your wallet (NEP-413) — it is not a transaction and costs nothing. Keys are tied to the account you log in with.

Authentication#

Send your key with every request, in the X-API-Key header:

Authorization: Bearer nt_live_… works too. As a last resort — a browser EventSource, which cannot send headers — the key may go in the query string as ?api_key=…; anything in a URL can end up in logs, so use a separate key for that.

Keep keys server-side. A key in front-end code is a key anyone can copy and spend your rate limit with. Call the API from your server or bot, and proxy what your users need. If a key leaks, revoke it under Get an API key and create a new one — we store only a hash of each key, so a lost key is replaced, never recovered.

The API is read-only: every endpoint is a GET. Nothing you call can move funds — trading returns transactions for your wallet to sign.

Rate limits#

Each key has a limit of requests per minute — 60 on the free plan, which is every key for now; ask us if you need more. Every response says where you stand:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute for this key.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetUnix time (seconds) when the minute resets.
Retry-AfterOn a 429: seconds to wait before retrying.
X-Request-IdUnique id of the request — include it when you contact support.

Over the limit you get 429 rate_limited. Wait for Retry-After, then continue; back off exponentially on repeated 429 or 5xx. Streams count once when opened, and each key may hold 5 open streams.

Polling tip: the trending board is recomputed every 20 seconds and token stats every few seconds — polling faster only spends your limit. For anything faster, use the stream.

Errors#

Errors use standard HTTP status codes and one JSON shape:

StatusCodeWhen
400invalid_requestA parameter is missing, malformed or out of range. The message says which.
401unauthorizedNo key, or the key is unknown or revoked.
404not_foundNo such endpoint, or the token/wallet is not indexed.
405method_not_allowedAnything but GET.
429rate_limitedOver your per-minute limit. See Retry-After.
429too_many_streamsMore than 5 open streams on one key.
502upstream_errorThe data service returned an error. Retry with backoff.
503unavailableThe data service is not answering (a deploy, usually seconds). Retry.
500internal_errorOur bug. Retry, and send us the request_id if it persists.

Data conventions#

ThingFormat
Token and wallet idsNEAR account ids, exactly as on chain: neart-2.nearlytrade.near, alice.near, or 64-hex implicit accounts. A token's id is its contract.
NEAR amountsNumbers in whole NEAR (amount_near: 2.5). Fields end in _near.
USD amountsNumbers in US dollars, at the NEAR price of the moment of the trade for history, and the current price for "now" values. Fields end in _usd.
Token amountsExact raw integers as strings in the token's smallest unit (amount_raw: "1829386548437401950513835") — divide by 10^decimals (see the token's decimals). Display-only token amounts are plain numbers.
PercentagesNumbers from 0 to 100 (top10_pct: 42.7 = 42.7%). Fields end in _pct. Basis points end in _bps (100 bps = 1%).
TimeISO 8601 in UTC (2026-10-01T01:24:19.512Z). Windows are 5m 30m 1h 6h 12h 24h.
Missing valuesnull — not measured yet, or not applicable (a token with no pool has no liquidity). Fields are never left out.
PaginationLists take limit. Endpoints that page return meta.next_cursor; pass it back as cursor until it is null.
Linksurl opens the token on nearterminal.tech; icon_url is an image served by this API.

Versioning

The version is in the path (/v1). Within v1 we only add: new endpoints, new fields, new enum values. Fields are never renamed, removed or retyped in v1 — code that ignores unknown fields keeps working. Anything breaking ships as /v2, with v1 kept running alongside for at least 6 months. Changes are listed in the changelog.

Copy trading — the complete guide#

Copy trading on NEAR Terminal follows the wallets you choose: when they buy, your vault buys; when they sell, it sells — within limits you set on chain, with your own take-profit and stop-loss. Your NEAR stays in a smart contract that only you can withdraw from.

How it works#

1 · They tradeA wallet you copy buys or sells. Our indexer sees it in the block it lands in.
→
2 · Your rulesYour filters, sizes and on-chain limits decide: copy, resize or skip (with the reason).
→
3 · Your vault swapsThe NTrade Vault swaps on Rhea from your balance — signed by your browser or the operator.
→
4 · You track itPositions, PnL, TP/SL and every skip show on the Vault page.

The pieces:

  • NTrade Vault (vault.ntrade.near) — a smart contract holding the NEAR and tokens you deposit. It can only swap for you; withdrawing needs your own wallet's signature.
  • Copy engine — watches every trade on NEAR and turns the trades of the wallets you copy into swaps, by your settings.
  • Your limits — Max per trade and Max per day, stored in the contract. Nothing automated can exceed them, whatever happens on our side.

Before you start

  • A NEAR wallet: HOT, Meteor, Intear, MyNearWallet, OKX, Nightly, NEAR Mobile, Ledger and others work — click Log in on nearterminal.tech.
  • Some NEAR for the deposit, plus a little for your own wallet's transaction fees (deposits, limits and withdrawals are signed by you; automated trades are not — see Fees).

Step 1 · Open your vault and deposit#

  1. Open the Vault pageHeader → Vault (or nearterminal.tech/vault). You see NEAR in the vault, Tokens in the vault and Your wallet (available to deposit).
  2. DepositEnter an amount and confirm in your wallet. The NEAR is wrapped and credited to your balance inside the contract. Only deposit what you are willing to let the bot trade.
  3. Check it landedThe balance updates from the chain within seconds. Tokens bought by copy trades appear under Tokens in the vault with a live sell quote.

Step 2 · Set your limits#

Limits live in the contract, signed by your wallet. They cap every automated buy — by any mode, from any copied wallet:

LimitWhat it does
Max per tradeThe most NEAR a single automated buy may spend. A copy larger than this is reduced to it (and the trade notes "capped at your … per-trade limit"). Required: with no per-trade limit, nothing is copied.
Max per dayThe most NEAR automated buys may spend per day. Resets at 00:00 UTC (8:00 AM Philippine time). Buys that would pass it are skipped with "daily limit reached".

Start small. A good first setup: Max per trade 1–2 NEAR, Max per day 10 NEAR. Raise them once you have watched a day of copies and skips.

Step 3 · Choose how trades are signed#

A copy trade needs a signature. You choose who gives it:

Browser mode most private

  • Your browser creates its own trading key (Ed25519, kept non-extractable in the browser) and registers it in the contract as your session key.
  • Each copy trade is signed in your open tab within 45 seconds, then relayed on chain.
  • Nobody else can trade for you. Stops when the tab closes or the computer sleeps.
  • Needs a current browser (Chrome 137+, Firefox 129+, Safari 17+). One tab per account runs it; an Auto dot in the header shows it is live.

Always-on 24/7

  • You name ops.ntrade.near as your vault's operator, on chain.
  • Our server trades for you around the clock — browser closed, phone off.
  • The operator can call only the vault's swap, within your Max per trade and Max per day. It can never withdraw or send funds anywhere.
  • You trust our server to follow your copy settings (the contract enforces the limits, not the settings).

Switch modes or turn auto trading Off on the Vault page at any time. "Key is on another device — enable here to move it" means Browser mode was enabled elsewhere; enabling it here moves it to this browser.

Step 4 · Find wallets worth copying#

The CopyTrade page ranks wallets by profit over 1, 3 or 7 days or all time. To keep one-hit wonders off it, a wallet must:

  • have made money on at least 3 different tokens, and
  • have no single token above 70% of its profit — one lucky runner is not an edge you can copy (over half of each week's profitable wallets made everything on one token).

Open any wallet for its analysis: PnL per window, win rate, tokens won and lost, average holding time, every position By token with bought/sold, average market cap, transfers and airdrops. Before copying, check:

  • Win rate and spread — many small wins beat one huge one.
  • Holding time — a wallet that sells within seconds is hard to copy profitably: by the time your copy lands, the price has moved.
  • Size — a whale buying 500 NEAR moves the price; your copy buys after it, higher.
  • Tags — sniper, bot or dev wallets often trade in ways a copy cannot follow.

Track a wallet to see its trades in My tracked wallets on the Vault page (free, no vault needed). Copy a wallet to have your vault follow it.

Step 5 · Copy settings#

Press Copy on a wallet. Each copied wallet has its own settings:

SettingWhat it doesSuggested
Buy amount — FixedThe same NEAR on every copy buy.0.5–2 NEAR
Buy amount — % of their sizeA share of what they spend: they buy 20 NEAR at 10% → you buy 2 NEAR.5–20%
Sell with themWhen they sell part of their bag, you sell the same share of your position: they sell half → you sell half; they sell all → you sell all.On
Take profit %Sell the whole position once it is up this much — what is left at today's price plus what you already sold, against what it cost. Empty = off.50–200%
Stop loss %Sell the whole position once it is down this much from cost. Empty = off.30–50%
Min / Max market capOnly copy buys of tokens in this market-cap range. Max 500000 copies only small caps. Empty = no bound.Min 5,000
Min liquidity (NEAR)Skip tokens whose pool holds less NEAR: thin pools move a lot on your buy and are hard to sell.100+
Max buys per tokenHow many open positions of one token (from this wallet) you allow. 1 = only their first buy, ignore their repeat buys; 5 = follow up to 5. Counts from zero again once your positions close.1–2
Slippage %The worst price move accepted between the quote and the swap. If the price moves more, the pool refuses and nothing is spent.10–15% for new tokens

Every buy is still capped by your vault's Max per trade and counts toward Max per day. Press Save settings; changes apply to the next trade.

What happens when they trade#

They buy

  1. The trade is seen in its block. Trades older than 30 seconds when we see them are not copied — a late copy buys at a different price.
  2. Your mode is checked (Always-on, or Browser mode with an open tab).
  3. The token is checked against your market-cap and liquidity filters, and your open positions against Max buys per token.
  4. The size is computed (fixed, or % of theirs). Below 0.05 NEAR the copy is skipped; above Max per trade it is reduced to it.
  5. Max per day and your vault's NEAR balance are checked.
  6. A route is quoted on Rhea and the swap is sent — straight away (Always-on) or after your tab signs it (Browser mode, 45-second window).
  7. The position opens on the Vault page with entry market cap, cost and live PnL.

They sell

With Sell with them on, you sell the same share of your position that they sold of theirs. Sells go out before buys: exits matter more than entries.

Take profit and stop loss

Every open copy position is checked continuously against its TP/SL; when one is hit, the whole position is sold.

Skipped trades — and what to change#

Every trade that was not copied is listed under Why it was skipped, with the trade and the reason:

ReasonWhat to do
no vault yetDeposit on the Vault page.
auto trading is offTurn on Browser mode or Always-on.
Browser mode is on but no tab with its key is openOpen nearterminal.tech in the browser that holds the key — or switch to Always-on.
MC $… below your min / above your maxWorking as set; widen the range if you want these.
liquidity below … NEARWorking as set; lower Min liquidity to take thinner pools (riskier).
already holding N open positions of this tokenRaise Max buys per token to follow repeat buys.
buy size … under the 0.05 NEAR minimumRaise Buy amount or the % of their size.
your per-trade limit is not setSet Max per trade on the Vault page.
daily limit reachedRaise Max per day, or wait for 00:00 UTC.
not enough NEAR in the vaultDeposit more NEAR.
token needs a non-standard storage depositThe token's contract asks for an unusual storage payment the vault does not make; buy it manually.

Positions and withdrawing#

  • Copy positions shows each open position: copied from, entry and current market cap, cost, live value and PnL. Sell 50% / Sell 100% close it manually at a live quote.
  • Stop copying a wallet stops new copies; open positions stay until you sell them or TP/SL fires.
  • Turn off auto trading stops everything automated. Withdraw sends NEAR or tokens back to your wallet — always available, even if trading is paused.

Security model#

  • Non-custodial. Your funds are in the contract under your account. Withdrawing requires your wallet's full-access key (a 1 yoctoNEAR deposit only your wallet can attach). Nobody at NEAR Terminal can withdraw your funds.
  • Narrow operator key. Our server holds one function-call key of ops.ntrade.near, permitted to call only the vault's swap and swap_signed. It cannot transfer NEAR, withdraw, or call any other contract.
  • On-chain limits. Max per trade and Max per day are enforced by the contract itself.
  • Browser mode keys are created in your browser and never leave it; each signed instruction carries a nonce and an expiry, so it cannot be replayed.
  • Owner controls. The vault owner (NTrade) can pause trading and upgrade the contract. Withdrawals stay open while paused.

Copying is not a guarantee. A wallet's past profit does not predict yours: you enter after them, at a worse price, and new tokens can drop to zero. Only deposit what you can afford to lose, and use stop losses.

Fees#

WhatCost
Each copy buy or sell1% of the trade, taken in the swap (shown in every quote as "1% fee"), plus the pool's own fee and any token tax.
Gas for automated tradesPaid by NEAR Terminal's operator account.
Deposit, limits, mode changes, withdrawNormal NEAR gas from your wallet (fractions of a cent).
Tracking wallets, analysis, leaderboardFree.

FAQ and troubleshooting#

A wallet I copy bought, but nothing happened.

Look under Why it was skipped — every decision is logged with its reason. If the trade is not there at all, it was older than 30 seconds when seen (rare), or the wallet's copy is switched off.

My copy bought at a much higher price than theirs.

You buy after them, and on small tokens their own buy moves the price. Use Min liquidity, copy wallets that hold longer, and keep slippage realistic.

The swap failed with a slippage error.

The price moved more than your Slippage % between quote and swap; nothing was spent. Raise slippage for fast tokens (10–15%).

Browser mode keeps stopping.

It runs only while a tab is open and awake. Laptops and phones sleep tabs — use Always-on for 24/7 copying.

Can I copy several wallets?

Yes, each with its own settings. Your vault limits are shared across all of them.

Is my money safe if NEAR Terminal goes offline?

Yes. Copying stops, but your funds sit in the contract and you can withdraw with your wallet directly.

Copy trading with the API#

The API gives you the same building blocks to research wallets or run your own copier:

Trading with the API#

The API never signs anything and never holds a key. GET /v1/swap/quote finds the best Rhea route and, when you pass account, returns the exact transactions that account's wallet must sign. You sign and send them with your own wallet or library.

  1. QuoteAsk for a buy (spend NEAR) or a sell (spend tokens) with your slippage.
  2. CheckRead expected_out, minimum_out and route. Every transaction's receiverId is the NEAR Terminal router ntrade.near or the token contract itself — refuse anything else.
  3. Sign and sendIn order, from the same account. A buy may include storage registration for the token (0.00125 NEAR, once per token).

Quotes include the 1% platform fee. A quote is a snapshot: sign and send within a few seconds, or ask again. If the price moves past your slippage the swap is refused on chain and your funds stay where they were (gas is still spent).

Realtime streaming#

GET /v1/stream is a Server-Sent Events stream: one long-lived HTTP response that delivers events as they happen. Choose events with events:

EventFires whenData
tradeA token in your tokens list trades (needs tokens, up to 50).A trade (same shape as token trades).
token.createdA new token is deployed — on any launchpad.A token summary with creator.
token.multiplierA token reaches 2×, 3×, 4×… its launch price (with real liquidity and holders).token, symbol, multiple, market_cap_usd.
trending.enteredA token enters the trending top 15.token, rank, market_cap_usd.
trending.top1A new token takes #1 on trending.token, rank: 1.
readyOnce, when the stream opens.The events and tokens you subscribed to.

token subscribes to all token events and trending to both trending events. A comment line (: ping) arrives every 20 seconds to keep proxies from closing an idle connection.

Reconnecting

Connections drop — deploys, networks, laptops sleeping. Reconnect after a few seconds (the stream suggests 3 s with retry:). Events that happened while you were away are not replayed; on reconnect, fetch /v1/tokens/new or /v1/tokens/{id}/trades to fill the gap.

Recipes#

Token card for a Telegram bot

Alert when a token enters trending

Subscribe to trending.entered on the stream — no polling, and you hear about it the moment the board changes (it is recomputed every 20 seconds).

Track one launchpad's new tokens

Chart candles

API reference#

Every endpoint, with its parameters, code in cURL, JavaScript and Python, and a real response captured from the live API. Paste your key below to use Try it.

Used only for Try it requests to this server.

Machine-readable: openapi.json (OpenAPI 3.1) — import it into Postman, Insomnia or a code generator.

Loading…

Changelog#

DateVersionChange
2026-10-011.0.0First public release: tokens, new deploys from all launchpads, trending, mooners, trades, candles, holders, traders, early buyers, dev activity, tax, search, launchpads, wallets, leaderboard, swap quotes and the realtime stream.

Support and terms#

  • Support: team@nearterminal.tech · @usenearterminal. Include the request_id from the error or the X-Request-Id header.
  • Attribution: when you show our data publicly, link to the token's url on nearterminal.tech.
  • Fair use: do not share keys, resell the raw data feed, or work around rate limits with many keys. We may revoke keys that do.
  • No advice: data is provided as is, for information. Nothing here is financial advice; on-chain trading carries the risk of total loss.