> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Bridge Intents
> [Alpha Preview] List bridge intents, newest-first, with cursor pagination.
**Alpha Preview** — Endpoints and response shape may change without notice.
Paginated history of bridge intents — every bridge attempt with its lifecycle
status, amounts (token + USD), token metadata, transaction hashes, and
per-step timestamps. Newest-first.
## Scoping
At least one scoping dimension is required — the endpoint never runs an
unbounded scan:
* `wallet` — intents where the address is the **sender or the recipient**.
* `customerId` — intents created with any API key owned by that customer.
* `apiKey` — intents created with that specific API key.
`customerId` and `apiKey` are mutually exclusive (at most one). `wallet` can be
combined with either to narrow a customer/key scope to one address.
Note that `apiKey` is both the auth credential and a scope: passing
`?apiKey=` filters results to intents created with that key. To list a
wallet's intents across **all** keys, authenticate with the
`Authorization: ` header and pass only `wallet`. An unknown or revoked
`apiKey` returns `404`.
## Query parameters
| Name | Required | Notes |
| -------------------- | ---------------- | --------------------------------------------------------------- |
| `wallet` | one of the three | Sender **or** recipient address. EVM hex or Solana base58. |
| `customerId` | one of the three | All intents from keys owned by this customer. |
| `apiKey` | one of the three | Intents created with this key. |
| `status` | no | Filter by lifecycle status (see table below). |
| `originChainId` | no | Chain id, name, or alias — `evm:8453`, `base`, `8453` all work. |
| `destinationChainId` | no | Same formats as `originChainId`. |
| `limit` | no | Page size, 1–100. Default `50`. |
| `cursor` | no | Opaque, from the previous page's `pagination.nextCursor`. |
Unknown chains, malformed wallets, and malformed cursors return `400`.
## Response
```json theme={null}
{
"data": [
{
"intentId": "52ec786-5ddbe3f-dff",
"status": "filled",
"originChainId": "evm:42161",
"destinationChainId": "solana:solana",
"sender": "0xa57c9583d1656a6cbb0c62c3a6c7b264f644ac25",
"recipient": "2ytTkFGy8EpbrRY56kjKQ6L1hmqCqbuQArqd6VeNyJK1",
"originToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"originMeta": { "name": "USDC", "symbol": "USDC", "logo": "https://metadata.mobula.io/assets/logos/..." },
"destinationToken": "B4ptaVsUe6YbtBwAS38WFeweSrVNfQLCcj9JRrtjU8vn",
"destinationMeta": { "name": "SOLdiers", "symbol": "SOLDIERS", "logo": "https://metadata.mobula.io/assets/logos/..." },
"amountIn": "7887660",
"amountOut": "7881497",
"amountInUsd": 7.88766,
"amountOutUsd": 7.881497,
"depositTxHash": "0xabd6e3210b9f495921bf1b096a8fe48dccaa3348bce45ab8ec901c4229528aec",
"fillTxHash": "5xL...",
"settleTxHash": "0x1d967fe2f6ab1ec1d8596b2faf80bcec3ccc341e61c6fddb34d9dd2b710dced6",
"latencyMs": 487,
"timestamps": {
"depositDetected": 1784183450897,
"fillSent": 1784183451200,
"fillConfirmed": 1784183451384,
"settled": 1784183452168
},
"createdAt": 1784183450000
}
],
"pagination": { "limit": 50, "pageEntries": 1, "nextCursor": "MjAyNi0wNi0yNFQxMzo0Njo0Mi44MzNafGNhMmYw..." }
}
```
Two differences from `/status/{id}` worth flagging:
* `amountIn` / `amountOut` are **raw base units** (not decimal-adjusted) —
`"7887660"` above is 7.88766 USDC (6 decimals). Use `amountInUsd` /
`amountOutUsd` for display, or divide by the token's decimals.
* Timestamps are **epoch milliseconds**, not ISO strings.
`originMeta` / `destinationMeta` carry token name/symbol/logo, with `null`
fields when the token isn't indexed. `latencyMs` is the deposit-detected →
fill-confirmed delta (null when the intent never filled, e.g. a refund).
## Status lifecycle
Happy path: `pending → deposited → filling (→ broadcasted → replaced) → filled
→ settling → settled`. Failure path: `filling → retrying → refunded` or
`failed`; `settling → settle_lost` when reconciliation could not confirm
settlement. From the user's perspective, `filled` (and later `settled`) means
funds were received; `refunded` means the deposit was returned on the origin
chain. See [Bridge Status](/rest-api-reference/endpoint/bridge-status) for the
statuses the live polling endpoint emits.
## Pagination
Cursor-based (keyset), newest-first. `pagination.nextCursor` is non-null when
the page was full — pass it back as `cursor` for the next page; `null` means
you've reached the end.
```typescript theme={null}
const API = "https://api.mobula.io";
const KEY = "YOUR_API_KEY";
let cursor: string | null = null;
do {
const url = new URL(`${API}/api/2/bridge/intents`);
url.searchParams.set("apiKey", KEY);
url.searchParams.set("wallet", "0xYourWallet");
if (cursor) url.searchParams.set("cursor", cursor);
const { data, pagination } = await (await fetch(url)).json();
for (const intent of data) console.log(intent.intentId, intent.status);
cursor = pagination.nextCursor;
} while (cursor);
```
## OpenAPI
````yaml get /2/bridge/intents
openapi: 3.0.0
info:
version: 1.0.0
title: Mobula API
description: >-
Documentation of the Mobula API
**Demo API**: The default server (demo-api.mobula.io) is a demo API with
rate limits.
For production use, please use api.mobula.io with an API key from
https://admin.mobula.io
servers:
- url: https://demo-api.mobula.io/api/
description: Demo API (rate limited, for testing only)
- url: https://api.mobula.io/api/
description: Production API (requires API key)
security: []
tags:
- name: V2 - Token
description: Token details, price, security, ATH, and holder data
- name: V2 - Market Data
description: Market details, OHLCV history, and lighthouse metrics
- name: V2 - Trades
description: Token trades, enriched trades, and trade filters
- name: V2 - Wallet
description: Wallet positions, activity, trades, analysis, and labels
- name: V2 - Assets
description: Cross-chain asset details and price history
- name: V2 - Swap
description: Swap quoting and execution
- name: V2 - Perps
description: Perpetual futures quoting, execution, and positions
- name: V2 - Bridge
description: Cross-chain bridge quoting and intent status (Alpha Preview)
- name: V2 - DeFi
description: Bonding pools and pulse data
- name: V2 - Search
description: Universal fast search
- name: V2 - Usage
description: Per-key API and WebSocket usage history
- name: V2 - Blockchains
description: System metadata and chain listings
- name: V2 - Prediction Markets
description: >-
Polymarket markets/events, wallet positions, and the full execution stack
(auth, order build/submit/cancel, approvals, pUSD wrap/unwrap, deploy,
deposit/withdraw, redeem). Alpha — see /api/2/pm/*.
- name: V1 - Market Data
description: Market prices, history, sparklines, pairs, and multi-data
- name: V1 - Wallet
description: Wallet portfolio, transactions, history, and NFTs
- name: V1 - Token
description: First buyers
- name: V1 - Trades
description: Market trades by pair
- name: V1 - Metadata
description: Token metadata, categories, and news
- name: V1 - Assets
description: List all assets
- name: V1 - Search
description: Search for assets, tokens, and pairs
- name: V1 - DeFi
description: Bonding pool pulse data
- name: V1 - Blockchains
description: Blockchain listings, pairs, and stats
- name: V1 - Webhooks
description: Webhook management
- name: V1 - Feed
description: Custom feed creation
paths:
/2/bridge/intents:
get:
tags:
- V2 - Bridge
summary: List bridge intents
description: >-
[Alpha Preview] Paginated bridge-intent history, newest-first. Scope by
wallet (matches sender or recipient), by customerId (all intents created
with keys owned by that customer), or by apiKey (intents created with
that key) — at least one is required; customerId and apiKey are mutually
exclusive. Optionally filter by status and origin/destination chain, and
page with the opaque cursor from pagination.nextCursor.
parameters:
- schema:
type: string
description: >-
Wallet address — returns intents where it is the sender or the
recipient.
required: false
description: >-
Wallet address — returns intents where it is the sender or the
recipient.
name: wallet
in: query
- schema:
type: string
description: Scope to all intents created with API keys owned by this customer.
required: false
description: Scope to all intents created with API keys owned by this customer.
name: customerId
in: query
- schema:
type: string
description: Scope to intents created with this API key.
required: false
description: Scope to intents created with this API key.
name: apiKey
in: query
- schema:
type: string
enum:
- pending
- deposited
- filling
- broadcasted
- replaced
- filled
- settling
- settled
- settle_lost
- retrying
- refunded
- failed
description: Filter by lifecycle status.
required: false
description: Filter by lifecycle status.
name: status
in: query
- schema:
type: string
description: >-
Filter by origin chain (id, name, or alias — e.g. "evm:8453",
"base").
required: false
description: >-
Filter by origin chain (id, name, or alias — e.g. "evm:8453",
"base").
name: originChainId
in: query
- schema:
type: string
description: Filter by destination chain (id, name, or alias).
required: false
description: Filter by destination chain (id, name, or alias).
name: destinationChainId
in: query
- schema:
type: integer
minimum: 1
maximum: 100
description: Page size (1-100, default 50).
required: false
description: Page size (1-100, default 50).
name: limit
in: query
- schema:
type: string
description: Opaque cursor from the previous page's pagination.nextCursor.
required: false
description: Opaque cursor from the previous page's pagination.nextCursor.
name: cursor
in: query
responses:
'200':
description: Bridge intents, newest-first, with cursor pagination.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
intentId:
type: string
status:
type: string
enum:
- pending
- deposited
- filling
- broadcasted
- replaced
- filled
- settling
- settled
- settle_lost
- retrying
- refunded
- failed
originChainId:
type: string
destinationChainId:
type: string
sender:
type: string
recipient:
type: string
originToken:
type: string
originMeta:
type: object
properties:
name:
type: string
nullable: true
symbol:
type: string
nullable: true
logo:
type: string
nullable: true
required:
- name
- symbol
- logo
destinationToken:
type: string
destinationMeta:
type: object
properties:
name:
type: string
nullable: true
symbol:
type: string
nullable: true
logo:
type: string
nullable: true
required:
- name
- symbol
- logo
amountIn:
type: string
description: >-
Raw amount in the origin token's base units (not
decimal-adjusted).
amountOut:
type: string
nullable: true
description: >-
Raw amount in the destination token's base units
(not decimal-adjusted).
amountInUsd:
type: number
nullable: true
amountOutUsd:
type: number
nullable: true
depositTxHash:
type: string
nullable: true
fillTxHash:
type: string
nullable: true
settleTxHash:
type: string
nullable: true
latencyMs:
type: number
nullable: true
timestamps:
type: object
description: Per-step timestamps, epoch milliseconds.
properties:
depositDetected:
type: number
nullable: true
fillSent:
type: number
nullable: true
fillConfirmed:
type: number
nullable: true
settled:
type: number
nullable: true
required:
- depositDetected
- fillSent
- fillConfirmed
- settled
createdAt:
type: number
description: Intent creation time, epoch milliseconds.
required:
- intentId
- status
- originChainId
- destinationChainId
- sender
- recipient
- originToken
- originMeta
- destinationToken
- destinationMeta
- amountIn
- amountOut
- amountInUsd
- amountOutUsd
- depositTxHash
- fillTxHash
- settleTxHash
- latencyMs
- timestamps
- createdAt
pagination:
type: object
properties:
limit:
type: number
pageEntries:
type: number
nextCursor:
type: string
nullable: true
required:
- limit
- pageEntries
- nextCursor
required:
- data
- pagination
````