Read Ripples markets

The rules, all of them

• Both block bounds are inclusive. fromBlock=10&toBlock=15 covers blocks 10 through 15.
• A window is at most 1000 blocks, counting both bounds. Wider is 400 invalid_request with a message naming the cap. Set your chunk size at or below it.
• Every response is a single named key, with no success or data wrapper and no top-level metadata.
• Every amount is an exact decimal string of up to 50 decimal places, never a JSON number. A JSON number is a double, and an eighteen-decimal token exhausts its significant digits on its first trade.
• /latest-block is the indexer's own cursor, never the chain. The head is the lowest indexed cursor across every source writing the chain, and /events stops at it, so a block is never served twice and never skipped. Stop at the head and you will never meet the cut.
• A window holding no events answers an empty list, never an error.
• The budget is 600 requests per 60 seconds per caller, which is ten times a two-second poll. Ask us if you want it higher; it is one setting.

Pulling one market, in order

Four calls. The head first, then a window of trades, then the market and its two assets. Every URL below is the real one for the Robinhood feed.

# Ask how far the feed has indexed. Never read past this block.
https://api.ripples.run/v1/dex/robinhood/latest-block
# block.blockNumber is the head. Everything below stops there.

# Read a window of trades. Both bounds are inclusive.
https://api.ripples.run/v1/dex/robinhood/events?fromBlock=57699981&toBlock=57700000
# Each event carries pairId, the legs, priceNative and reserves.

# Look up the market an event names. Its record is fixed at creation, so read it once.
https://api.ripples.run/v1/dex/robinhood/pair?id=0x…poolId
# asset0Id is the launch token and asset1Id is what it is priced in.

# Look up each side of the market, for decimals and supply.
https://api.ripples.run/v1/dex/robinhood/asset?id=0x…token
# decimals is always present. Supplies are exact decimal strings.

A market that has reached its target keeps answering on /pair. On Robinhood it keeps trading in the same pool under permanent liquidity, so its trades keep arriving on /events. On Solana the trading moves to Raydium CPMM, and the feed carries nothing further for it.

Every Ripples pool carries the same key: fee = 0 and tickSpacing = 200, on every chain and for every launch. Both are constants of the hook, so a deployment cannot change them and they are safe to hard code. The pool itself charges nothing; the hook charges everything.

On the pool manager

• Initialize. The pool exists. Its block is the market's creation for every aggregator that dates a pair.
• ModifyLiquidity. The launch's own position. The seed is the only one before graduation.
• Swap. Every trade. The amounts are the pool's, before the hook's cut: read TradeFeeCharged, CreatorTaxCharged and SnipeTaxCharged from the hook in the same transaction and subtract all of them to get what the trader received. TradeFeeCharged is emitted once per payee, so one trade lands two of them whenever the launch pays a creator as well as the treasury.

One thing that will make your numbers wrong

The hook takes its fee inside the swap, so the pool manager's Swap amounts overstate what the trader received by exactly the fee it charged. The fee lands in the swap's unspecified currency: on an exact-input buy that is the launch token, on an exact-input sell it is the asset the market is priced in, and on an exact-output swap it is whatever the swapper pays in, charged on top of the amount they named. Take the currency from the event rather than from the direction. Read TradeFeeCharged, CreatorTaxCharged and, inside the opening window, SnipeTaxCharged from the same transaction, and subtract all of them. Each carries the amount and the currency rather than a rate, precisely so a reader never has to reconstruct the schedule. None of them moves a token to any outside address: they are claims held inside the pool manager until they are claimed.

TradeFeeCharged is emitted once per payee, so one trade lands two of them whenever the launch pays a creator as well as the treasury, and the fee is their sum. CreatorTaxCharged is a different charge from a different rate: the trade fee is split with the treasury and the creator's tax is not, and a trader on a launch that sets one pays both.

On the launch hook

On the factories

Filter on the emitting address as well as the topic. Two factories are deployed on every chain, they are rotated separately, and 10 of their administrative events are byte-identical signatures. A reader keying on the topic alone attributes one rail's administration to the other.

On the token launch factory

On the collection factory

On the launch hook

On the launch lens

launchesOf is answered by a separate contract, listed per chain above where one is deployed. It holds no state, no money, and no permission: every field it returns it reads back out of the five hook views above and the pool manager, so a reader who does not want to trust it can reproduce the answer from those two addresses. Every chain the record publishes carries one. A chain listed without a lens has no batch read: enumerate its launches through the factory calls above and read each market from the hook views.

Placing a trade

A Ripples market is an ordinary Uniswap v4 pool, so any router that speaks v4 trades one. There is one size that needs ours. A launch's liquidity is a single position over a single bounded price range, and the hook refuses any swap that would end outside it, so a router that places its swap with a wide price limit walks a buy larger than the market has left straight into that refusal. The order reverts whole rather than taking what was there.

LaunchRouter at 0x22DB9B2c6C6DB56ABC3fc196E4bC1FBb9c4338a6 takes that order. swapExactIn(key, zeroForOne, amountIn, minAmountOut, recipient, deadline) places the swap with the range end as its price limit, so the pool fills to the end of the curve and stops, and returns (spent, amountOut). It pulls only spent from the caller through Permit2, so the part of the order the market could not take never moves. minAmountOut is a price rather than a quantity: the router holds spent * minAmountOut <= amountIn * amountOut, which is amountOut >= minAmountOut on an order that spends in full and the same rate on the part of one that does not.

Read the fill from Filled(poolId, sender, recipient, zeroForOne, amountIn, spent, amountOut). spent below amountIn is a partial fill and the market is at the end of its curve. The pool manager's Swap reports the part that filled and says nothing about the part that did not, so a reader that wants the difference has to take it from here. CurveEndReached is the revert on a market with nothing left to sell, and it is the answer to "this launch is ready to graduate" rather than a fault.

A program with an upgrade authority can still have its code replaced by that key. The manifest carries each program's binary and IDL sha256 from its deployment record, and the IDL row names the file under Interfaces that describes the program on that cluster. An earlier dual_fill program keeps the Crosscurrents it opened, and each is listed with the IDL it runs.

The key

dualFillKey = sha256(utf8(domain) || 0x00 || utf8(canonicalJson(core))), where the domain is ripples-dual-fill-v1 and canonical JSON has keys sorted, integers above 2^53 as decimal strings, no whitespace. The id in a Crosscurrent's URL is base64url(dualFillKey[0..16]), no padding, 22 characters. The core is the record both chains commit to, and @ripplesdotrun/agent-sdk recomputes the key from it before it signs.

core  {"deadline":1790000000,"dualFillFactory":"0x00000000000000000000000000000000000071f1","dualFillProgram":"EmuBkApiTEXxPG9JrsZ6xeHdVvP7tYpRQVemrjRdz8Wu","evmChainId":46630,"identitySha256":"311a1911fcf4321fda99a8280f03d5e81df594a7e162f599e8d438e5aad1dc16","mode":"fill-first","nonce":"12345678901234567890","openAlone":false,"publicUntil":1789980000,"rhCreator":"0xd065914767ba406e17ff69dfa63d979eb3d7c0d9","rhTokenFactory":"0x0338754d997967402896c9d45dfd5352e68606ba","solanaCluster":"devnet","solanaCreator":"257dxMGYQNp7bb2BMXhDhqfj4fZkGAN2bkuM8cdHSpoU","solanaProgram":"RippcKjgg9pkjHY7RKp6R1K8jPGwq2BRSJcgbErufjF","termsSha256":"c1d53b286cd40bcf5d9e396a740890774bcd504714ccd70fda5a17a023cb5867","v":1}
key   0x7d706417a3d20dcafcc371f8f131876442711f88975490baefb4b3c38a3e9d78
id    fXBkF6PSDcr8w3H48TGHZA

V20 has none of these optional core keys, so its key hashes the core as printed:

• agent: present only when an agent is the creator.
• collectionSha256: present only for a Crosscurrent with a collection.

Finding both sides

• Robinhood. fillOf(rhCreator, dualFillKey) on the factory the core names in dualFillFactory. For an agent side, first read treasuryOf(rhCreator, dualFillKey) on agent.robinhood.factory: the treasury is the fill's creator.
• Solana. The fill is the program address of ["fill", solanaCreator, dualFillKey] under dualFillProgram. For an agent side, derive the agent from solanaCreator under agent.solana.program, then its vault, and use the vault as the fill's creator.

Events

Filter on the fills a factory created as well as the topic. A fill emits the same events whichever factory made it, and 11 signatures are shared this way. Take fill addresses from each factory's FillCreated, whose signatures differ, and treasury addresses from AgentDualFillCreated.

• DualFillFactory.FillCreated. The Robinhood side of a Crosscurrent with no collection or agent exists. The fill, its creator and the Crosscurrent key are the three topics, so one filter on the key finds the side without reading the data.
• DualFill.Opened. The fill bought its opening share and the market is trading. LinkedDualFill emits the same signature, so filter on fills the two factories created.
• LinkedDualFillFactory.FillCreated. The Robinhood side of a Crosscurrent with a collection exists. It carries the collection's terms after the launch's, so its topic differs from the token factory's FillCreated.
• LinkedDualFill.CollectionOpened. The collection and its vesting schedule exist, in the same transaction as Opened.
• DualFillAgentFactory.AgentDualFillCreated. An agent treasury was created, funded and made the creator of a fill in one transaction. The treasury is the fill's creator of record; the wallet that funded it is topic 1.
• DualFillAgentTreasury.OperatorRetired. The funder stopped the agent for good. The treasury refuses every operator call after it.
• DualFillAgentTreasury.RunwayReturned. A side that can never open sent the runway back to the wallet that funded it.

Interfaces

The API

Every path below is on https://api.ripples.run. A route that needs a session takes one from a Robinhood wallet: POST /v1/auth/evm/challenge returns a message to sign, and POST /v1/auth/evm/verify exchanges the signature for a session.

Every answer about a Crosscurrent starts with statusLabel and summary, the words ripples.run shows.

The addresses on this page are the current generation. An earlier token launch factory still holds the launches it made, and those markets still trade, so it still answers launchCount and launches for them. An indexer covering every Ripples market on Robinhood reads both factories, and both are named in the address list. Every market either one created shares the same launch hook and the same pool key, so a reader filtering on the hook sees all of them without knowing which factory made which.

The same document as JSON is at /integrate/manifest.json. If an address here ever disagrees with the chain, the chain is right and we want to hear about it: the support page reaches us.