@gumag/bridge

中文文档
0.1.0发布于 2026/11/05MITTypeScriptES Module近 30 天下载 4993

Swap and bridge between EVM chains, Solana and Sui with the GUM bridge API: quote, execute with the user's wallet, watch.

原始使用文档
文档目录9 节
  1. Wallets
  2. What is checked
  3. Execution options
  4. Chains, tokens and amounts
  5. Errors
  6. Quotes as they arrive
  7. Other calls
  8. Package
  9. License

@gumag/bridge

Swap and bridge between EVM chains, Solana and Sui with the user's own wallet. The GUM bridge API picks the route, builds every transaction and tracks delivery; this package asks the wallet to sign and tells the API what it signed.

import { createBridge } from "@gumag/bridge";

const bridge = createBridge();
const quote = await bridge.quote({
  from: { chain: "evm:8453", token: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" },
  to: { chain: "evm:42161", token: "0xaf88d065e77c8cc2239327c5edb3a432268e5831" },
  amount: "100",
  sender, recipient,
});
const order = await bridge.execute(quote, { wallet: window.ethereum });
for await (const status of bridge.watch(order.id)) render(status);
npm install @gumag/bridge

viem, @solana/web3.js 1.x and @mysten/sui are peer dependencies, so your app's copies are shared: npm and pnpm install any that are missing (with Yarn, add them yourself).

Wallets

Pass the wallet for the chain the transfer leaves from.

Fromwallet
EVMAn EIP-1193 provider: window.ethereum, or await connector.getProvider() with wagmi
SolanaA wallet adapter (useWallet()) or an injected provider, with signTransaction or signAndSendTransaction
Sui{ signAndExecuteTransaction } from dapp-kit's useSignAndExecuteTransaction()

The wallet must hold sender. execute switches an EVM wallet to the right network (adding it if the wallet doesn't know it), then prompts once per step: one prompt on Solana and Sui, two on EVM when the token needs an approval. Each signed step is reported to the API at once. execute resolves when the funds have left the wallet, with the order executing; watch follows it to delivered, refunded, failed or expired.

What is checked

The API builds every transaction. Before any prompt, this package checks the order without knowing any router:

  • A quote is kept only for the amount and tokens asked for, and its order must match it. Every step is on that network and paid by sender.
  • On EVM, an approval is of the sent token for no more than the amount, and no other call grants or moves tokens or calls the wallet itself. Native value and approvals, summed over the order, stay within the amount.
  • On Solana and Sui, no transaction hands over an account or a whole balance: no reassigned or nonce-locked account, token authority change, burn, approval past the amount, account closed to someone else, or transfer of the Sui gas coin.
  • A Solana wallet may add a priority fee to a transaction this package sends; any other change is refused. A transaction the API sends, or one another signer already signed, must come back exactly as built.
  • A deposit order sends exactly the amount of the token to the address it names, and nothing else.
  • No step is signed twice, and an order can't gain steps once signing starts.

What a router's own contract or program does with what it is sent is the API's choice; the wallet's transaction preview is the last check.

Execution options

execute(quote, { wallet, signal, onOrder, onSubmitted, onStep }):

  • wallet is a provider or adapter, or { signers } when your app already holds signers in the bridge's own shape.
  • signal cancels before the next wallet prompt; funds already sent are still reported.
  • onSubmitted fires the moment a funding transaction leaves the wallet, or is signed for the API to send, before the API is told. Persist the transfer there (order.id, step.n, txHash): a failed report cannot lose it.
  • onStep fires as each prompt opens and once it is reported, with the order.

Each step is signed from the order as the API last returned it, so the API can resize or rebuild what is left to sign after every report. A report the API doesn't answer is tried again after 1 s and 3 s; if it still fails, execute throws report-failed, and reportStep(orderId, n, txHash) sends it later (reporting twice changes nothing). An order the API rate-limits at creation is retried after Retry-After for up to 15 s. Once a funding step has reached a wallet without a clear refusal, ordering the same quote again from the same createBridge() client throws report-failed instead of prompting for it twice.

Chains, tokens and amounts

  • chain: an ID from chains(): evm:8453, solana:mainnet, sui:mainnet.
  • token: a contract address from tokens(), or native for the gas coin.
  • amount: a decimal in the token's units ("100", "0.5"), or base units as a bigint (100000000n). More decimals than the token has is an error, never rounded.
  • slippageBps: optional. Omitted, the pair sets it: 5 bps between two dollar stablecoins at their peg (USDC to USDC, USDT to USDC), 120 bps otherwise (ETH to ETH too), and GUM Universal Swap quotes at 2%, its floor; every quote's slippageBps says what applied. Set it to hold every route to one tolerance.

A quote is the best route with every route, best first, under alternatives. Amounts are base units (amountOut), and decimals under decimal (decimal.amountOut). Any alternative can be passed to execute.

Errors

Everything throws a BridgeError with a code, its order once there is one, and the wallet's, node's or request's own error as cause.

codeWhat to do
quote-expiredQuote again.
order-uncertainAn earlier try may hold this quote with the router. Quote again.
wallet-rejectedNothing was sent. Run execute again while the quote lasts.
wallet-missingPass the wallet that holds sender, for the source chain.
wallet-networkThe wallet isn't on the source network and couldn't switch. Nothing was sent.
insufficient-gasThe wallet can't pay the network fee. Nothing was sent.
simulation-failedThe wallet or network says it would fail. Nothing was sent; try another route.
wallet-changedThe wallet edited a transaction past its priority fee. Nothing was sent.
wallet-failedThe wallet failed. Nothing was sent unless onSubmitted fired.
unknown-chain, unknown-tokenUse an ID from chains() and an address from tokens().
no-routeNo router carries this pair or amount now; failures says why.
price-unavailableNo price to check the minimum against. Try another token.
invalid-orderA step failed a safety check. Nothing was signed.
step-out-of-order, step-conflictAnother tab is running this order. Follow it with watch.
report-failedFunds left but the API wasn't told. Call reportStep(); don't sign again.
rate-limited, unavailableRetry, after retryAfter seconds when set; watch waits these out.

Quotes as they arrive

quote() answers once every router has. stream() opens a WebSocket and yields a snapshot each time a router answers or refreshes, each with the same quotes shape, complete and best first:

const controller = new AbortController();
for await (const snapshot of bridge.stream(request, { signal: controller.signal })) {
  render(snapshot.quotes, snapshot.pending); // replace, never append
}

The API closes the socket after about five minutes; call stream() again. Any snapshot's quote can go to execute(). Needs a global WebSocket (browsers, Node 22+).

Before a wallet connects, leave out sender and recipient: quote() and stream() then return prices only, quotes with no id that execute() refuses. Quote again with both wallets once they connect.

Other calls

const { chains, routers } = await bridge.chains();
const { tokens } = await bridge.tokens({ chain: "evm:8453", query: "USDC" });
const order = await bridge.getOrder(id);
createBridge({ apiKey: "…", baseUrl: "https://bridge-api.gum.ag" });

routers are the routers your key's quotes can come from, each with the name and logo its routes carry (mono ones are drawn for dark pages): show them before the first quote, and a router added later shows up with no change on your side.

Without an apiKey you get the public routing profile. Receipts and Solana broadcasts go through GUM's public RPC proxy, so no RPC keys are needed.

Package

ESM only, with types. dist/ is the TypeScript in src/ compiled one file per module, not minified, with source maps, and both ship in the package. It has no install scripts. createBridge() and quotes load no library; the signing code and the chain libraries load on the first execute().

License

MIT.

版本与发布记录

@gumag/bridge 共发布 2 个版本,首次发布于 2026/11/05;过去 12 个月发布了 2 个版本。

版本发布日期距今
0.1.0latest2026/11/0512 天前
0.0.0-stage2026/11/0512 天前

关于 @gumag/bridge 的常见问题

@gumag/bridge 是什么?

Swap and bridge between EVM chains, Solana and Sui with the GUM bridge API: quote, execute with the user's wallet, watch.

如何安装 @gumag/bridge?

在项目目录运行 npm install @gumag/bridge,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:viem(>=2.33.1 <3)、@mysten/sui(>=2.26.2 <3)、@solana/web3.js(>=1.98.0 <2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gumag/bridge 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gumag/bridge 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gumag/bridge 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gumag/bridge 可以商用吗?

@gumag/bridge 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gumag/bridge 的下载量有多少?

根据 npm 官方下载统计,@gumag/bridge 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,993 次,日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gumag/bridge 还在维护吗?

最新版本 0.1.0 发布于 2026/11/05(12 天前);至今共发布 2 个版本,其中过去 12 个月发布了 2 个;首次发布于 2026/11/05。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。