# Integrate with Umbrae

Base mainnet · chain ID 8453. Maintained by Ignis AI Labs; authored by GPT-6 via Codex, 2026-09-08.

The [OpenAPI document](https://www.umbrae.io/openapi.json) describes the existing public market-data API. It requires no session, API key or wallet connection. [Human-readable developer docs](https://www.umbrae.io/dev#public-api) and an [agent discovery index](https://www.umbrae.io/llms.txt) point to the same interface.

## Choose a venue

Use one base URL below, then append the operation path. GeckoTerminal and DEX Screener paths are equivalent adapters for the same venue; using both does not supply independent market data.

| Venue | Base URL |
|---|---|
| DAMM | https://www.umbrae.io/api/public/geckoterminal/damm |
| DLMM | https://www.umbrae.io/api/public/geckoterminal/dlmm |
| DAMM, DEX Screener alias | https://www.umbrae.io/api/public/dexscreener/base/damm |
| DLMM, DEX Screener alias | https://www.umbrae.io/api/public/dexscreener/base/dlmm |

DAMM uses dynamic-fee constant-product pricing. DLMM uses discrete liquidity bins. The DLMM listing adapters expose curated current-stack pools, not every factory-created pool. An unknown or unlisted DLMM pool returns 404. Factory permission to create a pool is separate from admission to the listing adapter.

## Start with a read

```sh
curl --fail --silent --show-error \
  https://www.umbrae.io/api/public/geckoterminal/dlmm/latest-block
```

The response contains `block.blockNumber` and `block.blockTimestamp`. This is the last indexed block, not a promise that the indexer has reached the chain head.

| Operation | Required query parameters | Result |
|---|---|---|
| `GET /latest-block` | None | `{ "block": { ... } }` |
| `GET /asset` | `id`: token address | `{ "asset": { ... } }` |
| `GET /pair` | `id`: pool address | `{ "pair": { ... } }` |
| `GET /events` | `fromBlock`, `toBlock`: non-negative integers, inclusive | `{ "events": [ ... ] }` |

There is no paginated pool-list operation in this adapter API. Obtain pool addresses from factory enumeration or the protocol's subgraph, then check adapter coverage with `/pair`. Never infer pool membership from a token symbol.

## Indexing sequence

1. Read `/latest-block` and compare it with your last processed block.
2. Fetch `/events` from your next unprocessed block through that indexed block. `toBlock` must be at least `fromBlock`. Split backfills into bounded ranges appropriate to your client timeout; the adapter does not publish a maximum range.
3. Resolve new pool and token addresses through `/pair` and `/asset`.
4. Sort events by `(block.blockNumber, eventIndex)` and deduplicate by `(txnId, eventIndex)`. `txnIndex` is currently a placeholder zero, not the actual transaction position within its block.
5. Commit your cursor only after processing a successful response. An empty event list is a valid result, not an upstream error. Replay an overlap window when reconciling reorganizations; these responses do not contain block hashes or a finality guarantee.

DLMM events contain swaps only. DAMM also includes joins and exits. A swap recipient or `maker` is not proof of a human trader, an AI operator, or a unique end user; routers and contract wallets can appear in transaction paths.

## Units and field meaning

- REST event amounts, reserves and optional total supply are decimalized token-unit strings. Preserve decimal precision. These differ from raw base-unit values commonly returned by contracts and the DLMM subgraph.
- `priceNative` is token-1 amount divided by token-0 amount for the trade. It is not a current quote or a USD price. Numeric strings may use scientific notation.
- DAMM `asset0`/`asset1` map to the adapter's token-0/token-1 order. DLMM maps them to tokenX/tokenY. Read the pair response; do not assume WETH is always tokenY.
- DLMM `feeBps` is the base swap fee. `metadata.binStep` is bin spacing, a separate quantity. Dynamic execution fees require a fresh contract quote.
- Fields such as creation block, creation transaction, supply and fee can be absent when unavailable. Missing is not zero.
- Event `reserves` come from the pair state supplied by the indexer when queried. Do not treat them as verified historical post-event reserves.

## Retry and capacity policy

Responses may carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. On HTTP 429, honor `Retry-After` (seconds) before retrying. On HTTP 502, retry with bounded exponential backoff and jitter without advancing your cursor. HTTP 400 means correct the request; HTTP 404 means the asset/pool is unknown or outside the adapter's coverage.

Successful smoke checks do not establish a throughput guarantee. Agree sustained request rates with the integration team before running a high-volume client. Cache stable metadata, not stale executable quotes; do not turn an upstream failure or empty discovery result into a long-lived cached absence.

## Trading and liquidity provision

Market-data discovery and financial execution are separate interfaces. This OpenAPI document does not advertise a public transaction-building, deposit, withdrawal or signing operation.

The [V2 ABI index](https://www.umbrae.io/docs/dev/abi/v2/index.json) provides copies of the application ABI bundle and content hashes. It is an interface reference, not proof that a particular address currently runs that implementation. Confirm the target pool, factory, proxy implementation, pause state and caller authorization on-chain before executing. Historical contract examples in the wider documentation may refer to older deployments.

For swaps, quote live, bind minimum output and input amount, identify the actual approval spender, simulate from the real caller, and wait for a successful receipt. Keep signing authority in the caller's wallet. For native ETH, a wrap is a preparation step rather than a completed trade. LP clients must handle multi-transaction claims and withdrawals, retain progress across retries, and distinguish returned principal from fees.

App endpoints outside `/api/public/` are not a versioned external contract. Some reads, including Base swap quotes, are anonymous. Protected handlers use sessions or scoped API keys. Account keys resolve to the account's primary wallet; the swap builder requires write scope and binds caller and recipient to that wallet. That model is suitable for an account-owned bot, not an arbitrary-recipient aggregator.

Before production integration, establish schema compatibility, both swap directions, allowance and balance preconditions, stale quote rejection, failure recovery, and complete deposit/claim/exit behavior against the intended deployment.