Quickstart

This runs a complete bridge from Node with keys your server holds: the shape of a bot, a treasury move or a test script. A browser app does the same steps through your backend, or with your project id: see Browser apps.

Server-held keys are for test networks and for your own funds. Never ask users for their keys; they sign in their own wallets.

Get a key

Make a secret API key (c8n_sk_…) in the hub dashboard. Keep it in your server’s secret store, or in a git-ignored .env file as HUB_API_KEY. See Testing.

Create the client

import { createInteropClient, hubTransport } from "@c8ntinuum/infinity-interop-sdk/server";

const client = createInteropClient({
  transport: hubTransport({
    baseUrl: process.env.HUB_BASE_URL!, // the hub's origin, e.g. https://proxy-api.infinimesh.net
    apiKey: process.env.HUB_API_KEY!, // c8n_sk_…
  }),
});

The transport sends the key in x-api-key on every call, under /v1: there is no sign-in and no session to renew. It refuses, before any call, a value that is not a secret key (a project id, for example) with a message that says so.

Pick a route from the catalog

import { toBaseUnits } from "@c8ntinuum/infinity-interop-sdk";

const catalog = await client.getCatalog();
const eth = catalog.resolveAsset("eip155-1", "eth");
if (eth?.kind !== "declared" || eth.asset.decimals === undefined) throw new Error("ETH is not on this hub");
const amount = toBaseUnits("0.05", eth.asset.decimals); // "50000000000000000"

Amounts are always decimal strings in base units. Build your pickers from the catalog rather than hard-coding chains, assets or contract addresses: they move when the hub is redeployed.

Get a quote and check it

const me = "0x…"; // the account that pays and receives here

const quote = await client.getQuote({
  sourceChain: "eip155-1",
  sourceAsset: "eth",
  destChain: "eip155-8888",
  destAsset: "ctm",
  amount,
  sourceAccount: me,
  recipient: me,
});

const report = await client.vetQuote(quote);
console.log(quote.lane.kind, quote.amountOut, report.ok);

quote.lane.kind says what the user will do (here wrap-native: one transaction). vetQuote compares every field that moves money with your request and the catalog. executeQuote runs the same checks again right before signing, so this step is for showing them, not a requirement.

Execute it

import { privateKeyToAccount } from "viem/accounts";
import { evmWalletFromAccount } from "@c8ntinuum/infinity-interop-sdk/evm";

const evm = evmWalletFromAccount({
  account: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`),
  rpcUrls: { 1: process.env.RPC_EIP155_1!, 8888: process.env.RPC_EIP155_8888! },
});

const result = await client.executeQuote({
  quote,
  wallets: { evm },
  onEvent: (event) => {
    if (event.type === "step") console.log(event.step, event.status, event.transactionHash ?? "");
    if (event.type === "filled") console.log("the recipient is paid");
  },
});
console.log(result.orderId, result.outcome); // "success" once the chain shows it settled

The SDK re-quotes if too little time is left to sign, sends the transaction, registers the order with the hub, and follows it until the chain shows it settled.

Read the history

import { formatUnits } from "@c8ntinuum/infinity-interop-sdk";

for (const entry of await client.listAllOrders()) {
  const row = await client.summarizeOrder(entry);
  const { amount, decimals, symbol } = row.pay;
  const paid = decimals === undefined ? `${amount} (base units)` : formatUnits(amount ?? 0n, decimals);
  console.log(row.phase, paid, symbol);
}

With your key and no subject of your own, this is the history of hubTransport’s one subject (default): every order made that way, whoever placed it. A service that acts for users of its own names each one with subject, and then lists only that user’s orders (Executing on a server for your users). decimals is never guessed: a token the catalog does not list can come back without it. See Order history.

When something fails

Every error the SDK throws has a user-facing message and an action:

import { adviseError } from "@c8ntinuum/infinity-interop-sdk";

try {
  await client.executeQuote({ quote, wallets: { evm } });
} catch (error) {
  const advice = adviseError(error);
  console.error(advice.action, advice.message); // e.g. "change-amount", "No provider will take this amount…"
}

A refused key throws a HubError whose isCredentialRefused is true (EPX0001: missing or malformed; EPX0002: unknown, revoked or expired). Fix the key before calling again: 20 refused credentials within a minute lock your IP out for the rest of that minute (EPX0081). See Errors for the full list.

The runnable version

The SDK repository’s examples/node-quickstart has this as scripts, configured by a .env with HUB_BASE_URL and HUB_API_KEY: pnpm smoke (a read-only check of a hub, starting with one call that checks your key), pnpm catalog, pnpm quote, pnpm bridge, pnpm orders and pnpm refund. See Testing.

Get started

Core concepts

Resources

API reference

SDK

SDK reference

When something fails

The runnable version

​When something fails

​The runnable version

When something fails

The runnable version