Developer quickstart

Create an Omniasset for an existing token, or add cross-chain transfers to your application using its OFT interface.

The starter targets the asset-router release and local development fixtures. Check release status before using any public-chain address.

Choose your path

Want fewer calls to manage? The TypeScript SDK handles OFT quotes, exact-amount approvals and transaction simulation using your existing viem clients. It is available from the repository now, ahead of its public npm release.

Before you start

Use a standard, non-rebasing ERC-20; fee-on-transfer tokens are unsupported. Choose the original token, origin chain and permanent creator together. Two creators of the same original token have independent assets and backing accounts. A community-created asset is not automatically the official issuer's asset.

Creation is one origin-chain transaction. Assets without an issuer compliance contract include the peers registered at creation; later peers require the issuer's approval. Remote tokens are created automatically on the first successful transfer or sync. You do not deploy per-token peers or configure DVNs.

See identity, security and OFT compatibility before integrating.

Install the runnable starter

Install Node.js 22+ and Bun. In a fresh folder, run:

bun init -y
bun add viem@2.52.2
curl -fLO https://www.omnisea.io/docs/examples/abi.ts
curl -fLO https://www.omnisea.io/docs/examples/deployments.json
curl -fLO https://www.omnisea.io/docs/examples/quickstart.ts
curl -fLO https://www.omnisea.io/docs/examples/run.ts

These files become available with this documentation deployment. In a repository checkout, they are already under web/public/docs/examples. The ABI and deployment snapshot are generated from the same sources used by the app. Pin a reviewed copy for your integration.

Create an untracked .env file. Replace every placeholder with your local fixture values. Never commit a private key or reuse a funded production key in examples.

RPC_URL=http://127.0.0.1:8545
CHAIN_ID=31337
ROUTER=0x_REPLACE_WITH_LOCAL_ROUTER
LENS=0x_REPLACE_WITH_LOCAL_LENS
TEST_PRIVATE_KEY=0x_REPLACE_WITH_DISPOSABLE_TEST_KEY
TOKEN=0x_REPLACE_WITH_ORIGIN_ERC20
CREATOR=0x_REPLACE_WITH_TEST_KEY_ADDRESS
RECIPIENT=0x_REPLACE_WITH_DESTINATION_RECIPIENT
DST_EID=30184
AMOUNT=1
MAX_NATIVE_FEE_WEI=10000000000000000
ACTION=create
BROADCAST=false

The destination EID is the local fixture's configured LayerZero endpoint ID, not its EVM chain ID. The fee limit is an example ceiling in source native base units, not a fee estimate. The starter expects an 18-decimal EVM native currency.

bun run run.ts

Expected result for ACTION=create: a simulated asset ID and adapter address, with no transaction sent. Set BROADCAST=true only when ready to submit. A successful receipt prints the authoritative AssetCreated event.

Transfer the asset

Set ACTION=transfer and change TOKEN to the source facade: the origin adapter or the remote OFT, not the original ERC-20. Keep BROADCAST=false initially.

The starter checks the RPC chain, router code, asset and route. It parses human-readable input with token decimals, handles origin approval, reads quoteOFT, sets the minimum received amount, quotes native payment, simulates and checks estimated gas funding. It prints a GUID after source confirmation when broadcasting.

If allowance is missing, simulation mode reports the approval needed without writing anything. Broadcasting may require a zero-reset approval, an exact-amount approval, then the send. Approvals can succeed even if the subsequent transfer fails; inspect receipts and never blindly repeat a source send.

Expected result: TransferSent.guid. Follow it using Track delivery. Source confirmation is not destination settlement.

Enable a later destination

Set ACTION=enable, restore TOKEN to the original ERC-20, and run on the origin with its permanent creator key. The example quotes through the Lens, checks your fee ceiling, and simulates enableChain before an optional broadcast. It prints the SyncSent GUID.

An already-enabled destination needs no enable call. If another remote source has stale route information, send syncAsset from the origin instead. See Manage your asset.

Use a connected wallet in your app

The starter uses a disposable private-key account to make local testing reproducible. In a browser, use your connected wallet's viem public and wallet clients; never request its private key. Keep the same resolve → approve → quote → simulate → write → track sequence. Revalidate account and chain after every wallet switch.

Download the complete implementation and runner. Continue with the production checklist.