# Integrate MadeOnSol REST and WebSocket with gap-free trade recovery

Go from an API key to a production stream: first REST call, stream token, Solana token:trades plus a Robinhood Chain channel, REST backfill after disconnects, exact dedupe ids and error handling.

Access: Pro and above for WebSocket and the trades endpoint

[Compare plans and subscribe](https://madeonsol.com/pricing#pricing)

Author: MadeOnSol

Updated: 2026-11-21

## Integration choice

Use one stream connection per process with named subscriptions, reuse the stream token, and fetch REST history only to fill an interval the stream reported as missing. A Solana token:trades backfill costs one request per 500 rows per mint per reconnect and nothing while connected.

## Before you start

- A Pro, Ultra or Business API key stored on your server.
- Node.js with the ws package and madeonsol-x402 4.9.0, or Python with madeonsol-x402[stream] 2.3.0.
- A store for processed ids and the resume cursor if delivery must survive your own restarts.

## Implementation steps

1. Create a key in the developer dashboard and keep it on your server. Make one GET /tokens/{mint}/trades call and read the coverage block: null fields are unknown, never zero.
2. Open the stream with the SDK (madeonsol-x402 4.9.0 on npm, 2.3.0 on PyPI). It calls POST /api/v1/stream/token on every connect; the token does not expire, so never rotate it on a timer.
3. Subscribe token:trades with filters.mints for Solana committed trades, and rhc:kol_trades for Robinhood Chain KOL trades. Both ride the same endpoint and the same stream token.
4. Persist the committed resume cursor and pass it back after a restart. token:trades is live only: after every reconnect, read GET /tokens/{mint}/trades for the gap. In TypeScript watchTokenTrades does this, including a second pass three seconds later.
5. Dedupe token:trades on event.event_id plus the mint, else tx_signature, wallet, action and mint. REST rows have no mint field, so use the path mint. Handle warning, gap and fatal events, and treat 429 and 503 with retry_after_seconds as back off, never as empty data.

## Use the exact trade id

A token:trade frame id is event.event_id followed by a colon and the mint. A netted row without an event id uses tx_signature, wallet_address, action and mint joined by colons. The two legs of a token-for-token swap share one event id, so the mint is what keeps them apart. Since 21 November 2026 the server sends this id; tokenTradeId(row, mint) in madeonsol-x402 4.9.0 builds the same value from a REST row and the path mint.

Ids stored before that change are bare and differ from the new ones. A client that kept its seen ids across the change can see a trade from just before the switch once more under its new id. Nothing is dropped. The SDK stream clients also dedupe token:trade frames on the id plus the mint.

## Know which data comes back

Event channels such as rhc:kol_trades resume from the committed cursor: a ring replay while the server process is the same, otherwise a bounded durable read of about 60 minutes and at most 2,000 rows per channel. Anything the server cannot rebuild is reported in a gap event with the channels, reasons and the cursor range that may be incomplete, never with a count.

token:trades is not replayed by the stream. watchTokenTrades reads the REST trades from the newest delivered trade minus 10 seconds, up to 20 pages of 500 rows per mint per pass, then once more after 3 seconds. A pass that runs out of pages or fails reports complete false and is retried on the next reconnect. Backfilled rows can arrive after newer live rows, so sort by block_time and slot if order matters.

## Stay inside plan limits

General stream connections: Pro 2, Ultra 5, Business 15, shared by Solana and Robinhood Chain channels. Named subscriptions per connection: 5, 10 and 20. token:trades mints per connection: 25, 100 and 250, refused with a channels_rejected warning above the cap, never truncated. A 4002 close means the connection limit is reached; release a stuck session under Active connections in the dashboard.

On REST, 401 means fix the key, 403 means the feature is above your plan, 429 and 503 carry retry_after_seconds and a Retry-After header. A 503 such as a ranking that is still being prepared is a fail-closed answer: retry later and never show it as zero. 402 only appears on the keyless pay-per-call routes.

## First REST call (Pro and above)

~~~bash
curl -H "Authorization: Bearer $MADEONSOL_API_KEY" "https://madeonsol.com/api/v1/tokens/$SOLANA_MINT/trades?limit=10"
~~~

## Solana trades with reconnect backfill (madeonsol-x402 4.9.0)

~~~javascript
import { createRESTClient, watchTokenTrades } from "madeonsol-x402";

const rest = createRESTClient(process.env.MADEONSOL_API_KEY);
const stream = rest.stream({ resume: null }); // pass your persisted cursor after a restart
stream.on("cursor", (cursor) => { /* persist the committed cursor */ });
stream.on("warning", (w) => console.warn("warning", w.code, w.rejected));
stream.on("gap", (g) => console.warn("unrecovered range", g.reasons, g.skipped));

const feed = watchTokenTrades({
  stream, rest, mints: [process.env.SOLANA_MINT],
  onTrade: (trade, { source, id }) => console.log(source, id, trade.action, trade.block_time),
  onBackfill: (r) => { if (!r.complete) console.warn("backfill incomplete", r.mint, r.error); },
});
// Robinhood Chain: createClient(key).stream() from robinhood-chain-x402,
// then subscribe({ subId: "rhc-kol", channels: ["rhc:kol_trades"] }).
~~~

## Common mistakes and fixes

- Dedupe token:trades on event.event_id alone. Fix: Add the mint; otherwise the second leg of a token-for-token swap is dropped.

- Expect the stream resume to return missed token:trades rows. Fix: Backfill from GET /tokens/{mint}/trades after every reconnect, or use watchTokenTrades.

- Run the REST backfill inside an awaited Python stream handler. Fix: Start it as a task; awaited handlers block the receive loop.

## Verify your integration

Drop the network for 30 seconds and for 2 minutes during traffic, then restart the process. Compare the trades you stored with GET /tokens/{mint}/trades for the same window: every row is present once, a token-for-token swap shows both legs, and any incomplete backfill was reported instead of silently skipped.

## Production checklist

- Handlers for warning, gap, fatal and error are registered and monitored.
- The committed cursor is persisted and passed back as resume after a restart.
- token:trades gaps are backfilled from REST and incomplete backfills are logged.
- Processed ids are stored with their effect, both swap legs included.
- Connection count stays within the plan limit.

## Frequently asked questions

### Is delivery exactly once?

No. Streams deliver at least once with stable ids. The SDKs drop duplicates they remember; your own store must make side effects idempotent across restarts.

### Can one connection carry Solana and Robinhood Chain channels?

Yes. Both use the same endpoint and stream token. The Python SDK accepts any channel on one socket; the TypeScript madeonsol-x402 client types Solana channels only, so TypeScript code usually opens Robinhood Chain channels with robinhood-chain-x402 on a second connection.

## Continue building

- [Build reliable MadeOnSol WebSocket recovery](https://madeonsol.com/docs/realtime-reliability)
- [Recover a WebSocket feed after a disconnect](https://madeonsol.com/docs/websocket)
- [Scale a MadeOnSol terminal to multiple viewers](https://madeonsol.com/docs/terminal-at-scale)

## Match your plan to your workload

Compare capacity, channel access and display rights before launching.

[Compare plans and subscribe](https://madeonsol.com/pricing#pricing)

## Related reference

- [Developer dashboard](https://madeonsol.com/developer)
- [Stream subscription builder](https://madeonsol.com/api-docs#stream-config)
- [Streaming reference](https://madeonsol.com/streaming)
- [Errors and rate limits](https://madeonsol.com/api-docs#errors)

[Canonical guide](https://madeonsol.com/docs/integration-quickstart)
