Bridge Intents

List bridge intents

curl --request GET \
  --url https://demo-api.mobula.io/api/2/bridge/intents

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://demo-api.mobula.io/api/2/bridge/intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://demo-api.mobula.io/api/2/bridge/intents"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://demo-api.mobula.io/api/2/bridge/intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "intentId": "<string>",
      "status": "pending",
      "originChainId": "<string>",
      "destinationChainId": "<string>",
      "sender": "<string>",
      "recipient": "<string>",
      "originToken": "<string>",
      "originMeta": {
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "inputToken": "<string>",
      "inputMeta": {
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "inputAmount": "<string>",
      "destinationToken": "<string>",
      "destinationMeta": {
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "amountIn": "<string>",
      "amountOut": "<string>",
      "amountInUsd": 123,
      "amountOutUsd": 123,
      "depositTxHash": "<string>",
      "fillTxHash": "<string>",
      "settleTxHash": "<string>",
      "refundTxHash": "<string>",
      "latencyMs": 123,
      "timestamps": {
        "depositDetected": 123,
        "fillSent": 123,
        "fillConfirmed": 123,
        "settled": 123
      },
      "fees": {
        "bridgeBps": 123,
        "bridgeUsd": 123,
        "integratorAddress": "<string>",
        "integratorUsd": 123
      },
      "createdAt": 123
    }
  ],
  "pagination": {
    "limit": 123,
    "pageEntries": 123,
    "nextCursor": "<string>",
    "resumeCursor": "<string>"
  }
}

GET

bridge

intents

List bridge intents

curl --request GET \
  --url https://demo-api.mobula.io/api/2/bridge/intents

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://demo-api.mobula.io/api/2/bridge/intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://demo-api.mobula.io/api/2/bridge/intents"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://demo-api.mobula.io/api/2/bridge/intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "intentId": "<string>",
      "status": "pending",
      "originChainId": "<string>",
      "destinationChainId": "<string>",
      "sender": "<string>",
      "recipient": "<string>",
      "originToken": "<string>",
      "originMeta": {
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "inputToken": "<string>",
      "inputMeta": {
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "inputAmount": "<string>",
      "destinationToken": "<string>",
      "destinationMeta": {
        "name": "<string>",
        "symbol": "<string>",
        "logo": "<string>",
        "decimals": 123
      },
      "amountIn": "<string>",
      "amountOut": "<string>",
      "amountInUsd": 123,
      "amountOutUsd": 123,
      "depositTxHash": "<string>",
      "fillTxHash": "<string>",
      "settleTxHash": "<string>",
      "refundTxHash": "<string>",
      "latencyMs": 123,
      "timestamps": {
        "depositDetected": 123,
        "fillSent": 123,
        "fillConfirmed": 123,
        "settled": 123
      },
      "fees": {
        "bridgeBps": 123,
        "bridgeUsd": 123,
        "integratorAddress": "<string>",
        "integratorUsd": 123
      },
      "createdAt": 123
    }
  ],
  "pagination": {
    "limit": 123,
    "pageEntries": 123,
    "nextCursor": "<string>",
    "resumeCursor": "<string>"
  }
}

Alpha Preview — Endpoints and response shape may change without notice.

Paginated history of bridge intents — every bridge attempt with its lifecycle status, amounts (raw + USD), token metadata, itemized fees, transaction hashes, and per-step timestamps. Newest-first by default; pass order=asc to walk it forward from a watermark (see Following the feed).

Scoping

At least one scoping dimension is required — the endpoint never runs an unbounded scan:

wallet — intents sent by that address (the depositor).
customerId — intents created with any API key owned by that customer.
apiKey — intents created with that specific API key.
intentId — a single intent; it scopes on its own, since the id is unique.

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: <key> header and pass only wallet. An unknown or revoked apiKey returns 404.

Query parameters

Name	Required	Notes
`wallet`	one of the four	Sending address. EVM hex or Solana base58.
`customerId`	one of the four	All intents from keys owned by this customer.
`apiKey`	one of the four	Intents created with this key.
`intentId`	one of the four	The single intent with this id. Use it to re-read one intent — a dead-letter retry, say — instead of re-paging the feed.
`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`.
`createdAfter`	no	Only intents created strictly after this time. Accepts epoch seconds, epoch milliseconds (what `createdAt` emits), or ISO-8601.
`createdBefore`	no	Only intents created at or before this time. Same formats.
`order`	no	`desc` (newest-first, the default) or `asc` (oldest-first).
`limit`	no	Page size, 1–100. Default `50`.
`cursor`	no	Opaque, from the previous page’s `pagination.nextCursor` or `pagination.resumeCursor`.

Unknown chains, malformed wallets, malformed cursors, and unparseable createdAfter / createdBefore values return 400.

Response

{
  "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/...", "decimals": 6 },
      "inputToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "inputMeta": { "name": "USDC", "symbol": "USDC", "logo": "https://metadata.mobula.io/assets/logos/...", "decimals": 6 },
      "inputAmount": "7887660",
      "destinationToken": "B4ptaVsUe6YbtBwAS38WFeweSrVNfQLCcj9JRrtjU8vn",
      "destinationMeta": { "name": "SOLdiers", "symbol": "SOLDIERS", "logo": "https://metadata.mobula.io/assets/logos/...", "decimals": 6 },
      "amountIn": "7887660",
      "amountOut": "7881497",
      "amountInUsd": 7.88766,
      "amountOutUsd": 7.881497,
      "depositTxHash": "0xabd6e3210b9f495921bf1b096a8fe48dccaa3348bce45ab8ec901c4229528aec",
      "fillTxHash": "5xL...",
      "settleTxHash": "0x1d967fe2f6ab1ec1d8596b2faf80bcec3ccc341e61c6fddb34d9dd2b710dced6",
      "refundTxHash": null,
      "latencyMs": 487,
      "timestamps": {
        "depositDetected": 1784183450897,
        "fillSent": 1784183451200,
        "fillConfirmed": 1784183451384,
        "settled": 1784183452168
      },
      "fees": {
        "bridgeBps": 5,
        "bridgeUsd": 0.003944,
        "integratorAddress": "0x1234...",
        "integratorUsd": 0.09
      },
      "createdAt": 1784183450000
    }
  ],
  "pagination": {
    "limit": 50,
    "pageEntries": 1,
    "nextCursor": null,
    "resumeCursor": "MjAyNi0wNi0yNFQxMzo0Njo0Mi44MzNafGNhMmYw..."
  }
}

Two differences from /status/{id} worth flagging:

amountIn / amountOut are raw base units (not decimal-adjusted) — "7887660" above is 7.88766 USDC. Divide by originMeta.decimals / destinationMeta.decimals to display, or use amountInUsd / amountOutUsd.
Timestamps are epoch milliseconds, not ISO strings.

originMeta / destinationMeta / inputMeta carry token name/symbol/logo/decimals, 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).

The token the user sold

Bridging from a token the bridge does not hold — anything but the native coin or USDC on that chain — swaps it first: the helper sells it for the origin chain’s native coin, and only then does the bridge see the funds. originToken is therefore the native coin, because that is what the bridge received and what a refund would return. inputToken / inputMeta / inputAmount describe the leg before that swap — what the user actually parted with:

{
  "originToken": "0x0000000000000000000000000000000000000000",
  "originMeta": { "symbol": "ETH", "decimals": 18 },
  "amountIn": "411241372356736",
  "inputToken": "0x18c11FD286C5EC11c3b683Caa813B77f5163A122",
  "inputMeta": { "symbol": "GNS", "decimals": 18 },
  "inputAmount": "1818901713804608659"
}

Read as: sold 1.8189 GNS, which became 0.000411 ETH, which is what got bridged. When no swap was needed, inputToken equals originToken and inputAmount equals amountIn. Both are null on intents created before these fields existed — fall back to originToken / amountIn there; they are never backfilled.

Refunds

A bridge that cannot deliver returns the deposit on the origin chain. refundTxHash is that transaction, and status is refunded. Two things to know when rendering one:

The refunded amount is in amountOut, denominated in the origin token (originToken / originMeta) — not the destination token it normally holds. It is the deposit minus the refund’s gas.
A swapped deposit is refunded in what the bridge held, so a user who sold GNS is paid back in ETH. The swap already happened on chain and cannot be undone.

refundTxHash is null on every intent that was not refunded.

Fees

fees itemizes what was already deducted — the amounts in amountOut / amountOutUsd are net of all of it:

Field	Meaning
`bridgeBps`	Mobula protocol fee in basis points, as applied to this intent.
`bridgeUsd`	That fee in USD (`bridgeBps` applied to `amountInUsd`).
`integratorAddress`	The integrator’s payout address, when the quote carried one.
`integratorUsd`	The integrator’s cut in USD.

integratorAddress / integratorUsd are null on intents quoted without an integrator fee. Destination gas is not itemized here — it is priced into the quote, not charged as a fee line.

Destination before the fill

Until the fill lands, destinationToken and recipient are chain-shaped placeholders, not the real values — the destination of an unfilled intent describes a trade the solver still has to execute. They become real on filled, settling, settled, settle_lost, refunded, and failed. Treat a non-terminal row’s destination as unknown rather than storing it.

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 for the statuses the live polling endpoint emits.

Pagination

Cursor-based (keyset) on (createdAt, id), in whichever order you asked for. The cursor is opaque — pass it straight back, and keep order identical across the pages of one scan or it will walk the wrong way.

nextCursor is non-null only when the page came back full, meaning there is at least one more page. null means you’ve reached the end of the scan.
resumeCursor marks where the page stopped, and is set whenever the page returned a row — including a partial one. It is what a follower resumes from; deriving a position from createdAt instead loses sub-millisecond ordering and can re-serve or skip a row.

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);

Following the feed

To keep an index in sync, page forward with order=asc and hold the last resumeCursor as your watermark. Every cycle resumes exactly where the last one stopped, so a cycle that returns nothing costs one request instead of re-paging the whole history from the newest row down.

// `cursor` is your durable watermark — persist it, not a timestamp.
let cursor: string | null = loadWatermark();

for (;;) {
  const url = new URL(`${API}/api/2/bridge/intents`);
  url.searchParams.set("apiKey", KEY);
  url.searchParams.set("order", "asc");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  // Cold start only: begin at a point in time instead of the first intent ever.
  else url.searchParams.set("createdAfter", String(Date.now() - 24 * 3600 * 1000));

  const { data, pagination } = await (await fetch(url)).json();
  for (const intent of data) await index(intent);

  // Commit the watermark only after the rows are durably indexed.
  if (pagination.resumeCursor) { cursor = pagination.resumeCursor; saveWatermark(cursor); }
  if (!pagination.nextCursor) await sleep(2000); // caught up
}

createdAfter is inclusive of nothing — it is strictly greater-than — so a timestamp cold start never re-delivers the row it names. Once you hold a cursor, drop createdAfter: the cursor is the more precise position.

Query Parameters

wallet

string

Wallet address — returns intents this address sent (the depositor). Recipient-side lookups are not served here.

customerId

string

Scope to all intents created with API keys owned by this customer.

apiKey

string

Scope to intents created with this API key.

intentId

string

Return the single intent with this id.

status

enum<string>

Filter by lifecycle status.

Available options:

pending,

deposited,

filling,

broadcasted,

replaced,

filled,

settling,

settled,

settle_lost,

retrying,

refunded,

failed

originChainId

string

Filter by origin chain (id, name, or alias — e.g. "evm:8453", "base").

destinationChainId

string

Filter by destination chain (id, name, or alias).

createdAfter

string

Only intents created strictly after this time — epoch seconds, epoch milliseconds, or ISO-8601. Pair with order=asc to page forward from a watermark.

createdBefore

string

Only intents created at or before this time — epoch seconds, epoch milliseconds, or ISO-8601.

order

enum<string>

Sort on creation time: desc (newest-first, default) or asc (oldest-first).

Available options:

asc,

desc

limit

integer

Page size (1-100, default 50).

Required range: 1 <= x <= 100

cursor

string

Opaque cursor from the previous page's pagination.nextCursor. Keep order identical across pages of one scan.

Response

200 - application/json

Bridge intents in the requested order, with cursor pagination. pagination.resumeCursor marks where a page stopped even when it was partial, so a follower can tail the feed; token meta carries decimals for the raw amounts, and fees itemizes the bridge and integrator cuts already deducted from amountOut.

data

object[]

required

Show child attributes

pagination

object

required

Show child attributes

⌘I

Introduction

Bridge

Perps Execution

Agentic Payments

Scoping

Query parameters

Response

The token the user sold

Refunds

Fees

Destination before the fill

Status lifecycle

Following the feed

Query Parameters

Response

​Scoping

​Query parameters

​Response

​The token the user sold

​Refunds

​Fees

​Destination before the fill

​Status lifecycle

​Pagination

​Following the feed

Query Parameters

Response

Scoping

Query parameters

Response

The token the user sold

Refunds

Fees

Destination before the fill

Status lifecycle

Pagination

Following the feed