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.

https://api.ripples.run/v1/tokenlist/robinhood.json

Launches the board leaves out are left out here too, and only the real $RIPPLES carries its name. When an entry is removed, the list’s major version goes up, so apps that follow the list drop it as well.

Every Ripples pool carries the same key: fee = 0 and tickSpacing = 200, on every hook and for every launch. Both are constants of the hooks, 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 own and leave out the hook's cut: TradeFeeCharged, CreatorTaxCharged and SnipeTaxCharged in the same transaction are the difference between them and what the trader paid or received.

One thing that will make your numbers wrong

The hook takes its fee inside the swap, so the pool manager's Swap amounts differ from what the trader paid or received by exactly what the hook charged. Every hook newer than LaunchHook charges its fee in the asset the market is priced in, whichever way the trade goes: before the swap when the trader named the amount in that asset, after it otherwise. LaunchHook charges 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, on top of the amount they named. Take the currency from the event. Read TradeFeeCharged, CreatorTaxCharged and, inside the opening window, SnipeTaxCharged from the same transaction and account for all of them. Each carries the amount and the currency. None of them moves a token during the swap: each is a balance the hook holds inside the pool manager for its payee, paid out when that payee claims it.

TradeFeeCharged is emitted once for each payee, so one trade can land several, and the fee is their sum. On FeeLiquidityHook one of them credits the market's own locker, which adds it to the market's locked liquidity. CreatorTaxCharged is a different charge at a different rate: the trade fee is split between its payees, and the creator's tax goes to the launch's creator income. A trader on a launch that sets one pays both.

On the hooks

Every hook emits these events from the same interface. CreatorTaxShareHook adds CreatorTaxSharingSet and HolderTaxCharged for the part of a creator's tax it passes to the token's holders.

On the factories

Filter on the emitting address as well as the topic. Several token and collection factories are deployed side by side, and 15 of their administrative events are byte-identical signatures. A reader keying on the topic alone attributes one factory's administration to another.

LaunchCreated carries the launch's whole tuple, so its topic changes with the tuple. The fee-liquidity factories, which the site creates on, append the creator's share of the trade fee and emit LaunchCreated(address,address,bytes32,address,address,(string,string,uint256,uint256,uint256,uint256,uint256,uint64,uint96,address,string,string,string,string,string,string,string,uint96)), topic0 0xd38b2b35d1a2a62304b3b1faa3406e344473ccae48dc7c15a55092cb2f540f7b. Decode each factory's events with its own tuple.

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 beside each hook above. 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.

Each hook has its own router, listed beside it above: a v4 pool's hook is part of its key, so a router built for one hook refuses another's pools. LaunchHook's is LaunchRouter at 0x22DB9B2c6C6DB56ABC3fc196E4bC1FBb9c4338a6, and every router takes the same call. 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. A buy on a market priced in ETH is paid as the call's value instead, exactly amountIn, and the router sends back what the market could not take in the same transaction. 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, which names dual_fill_dbc or a dual_fill program; both derive it from the same seeds. 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. An Open now Crosscurrent on Meteora has no fill and names no dualFillProgram: its Meteora config is the program address of ["dbc_config", solanaCreator, dualFillKey] under dual_fill_dbc, and the launchConfig account below names its pool.

Events

Filter on the fills a factory created as well as the topic. A fill emits the same events whichever factory made it, and 12 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 factories above are the ones the site creates on today. Earlier factories still hold the launches they made, and those markets still trade, so they still answer launchCount and launches for them. Every market any of them created is keyed to one of the hooks above, so a reader filtering the pool manager on those hooks sees every Ripples market on Robinhood without knowing which factory made it.

The machine-readable manifest 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.