@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.
| From | wallet |
|---|---|
| EVM | An EIP-1193 provider: window.ethereum, or await connector.getProvider() with wagmi |
| Solana | A 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 }):
walletis a provider or adapter, or{ signers }when your app already holds signers in the bridge's own shape.signalcancels before the next wallet prompt; funds already sent are still reported.onSubmittedfires 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.onStepfires 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 fromchains():evm:8453,solana:mainnet,sui:mainnet.token: a contract address fromtokens(), ornativefor the gas coin.amount: a decimal in the token's units ("100","0.5"), or base units as abigint(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'sslippageBpssays 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.
code | What to do |
|---|---|
quote-expired | Quote again. |
order-uncertain | An earlier try may hold this quote with the router. Quote again. |
wallet-rejected | Nothing was sent. Run execute again while the quote lasts. |
wallet-missing | Pass the wallet that holds sender, for the source chain. |
wallet-network | The wallet isn't on the source network and couldn't switch. Nothing was sent. |
insufficient-gas | The wallet can't pay the network fee. Nothing was sent. |
simulation-failed | The wallet or network says it would fail. Nothing was sent; try another route. |
wallet-changed | The wallet edited a transaction past its priority fee. Nothing was sent. |
wallet-failed | The wallet failed. Nothing was sent unless onSubmitted fired. |
unknown-chain, unknown-token | Use an ID from chains() and an address from tokens(). |
no-route | No router carries this pair or amount now; failures says why. |
price-unavailable | No price to check the minimum against. Try another token. |
invalid-order | A step failed a safety check. Nothing was signed. |
step-out-of-order, step-conflict | Another tab is running this order. Follow it with watch. |
report-failed | Funds left but the API wasn't told. Call reportStep(); don't sign again. |
rate-limited, unavailable | Retry, 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.