Skip to main content

Integrate Beyond in your dApp

Beyond's Frontend SDK​

The Frontend SDK is a TypeScript library that provides a simple interface to interact with Beyond's contracts and programmatically bridge assets between chains.

note

To simplify, in this section we refer to any non-Bitcoin blockchain (Ethereum, Solana, Bitcoin L2s...) as CHAIN, and to Bitcoin L1 as BTC_L1.

Installation​

To get started with the Beyond SDK, follow these simple steps:

bash
yarn add @beyond-tech/sdk
typescript
import { bridge } from '@beyond-tech/sdk'

bridge.test() // Output: 'gm Beyonder!'

Bridge CHAIN → BTC_L1​

Move tokens from any non-Bitcoin chain (Ethereum, Solana, Bitcoin L2s...) to Bitcoin L1.

bridge.toBitcoin(btcStandard, token, amount, toAddress[, referral])
Alternatively, if you prefer to bridge tokens with a custom integration (or manually via explorer):
  1. Use your favorite way to submit blockchain transactions (e.g. via CLI, or with an explorer like Etherscan).
  2. Locate the OriginalTokenBridge contract address for your desired chain in Beyond's deployment log.
  3. Read the contract's fee value.
  4. Call the contract's bridgeToXYZ function (e.g. bridgeToBrc20, or bridgeToRunes).

Parameters​

  • btcStandard — string: the Bitcoin token standard to use (BRC-20, Runes...)
  • token — string: the token symbol to bridge
  • amount — number: the amount to bridge
  • toAddress — string: the wallet address to receive the tokens
  • referral — string (optional): your referral's wallet address (for the Leaderboard, valid only for your first tx)

Returns​

  • Promise — string: tx ID

Example​

bridge.toBitcoin(
  'BRC-20',
  'USDT',
  1000,
  'tb1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa000000',
  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
)

Bridge BTC_L1 → CHAIN​

Move tokens from Bitcoin L1 to any other chain (Ethereum, Solana, Bitcoin L2s...).

bridge.fromBitcoin(btcStandard, token, amount, toChain, toAddress[, referral])
Alternatively, if you prefer to bridge tokens with a custom integration (or manually via explorer):
  1. Use your favorite way to submit Bitcoin transactions (e.g. via CLI, or with a wallet like UniSat).
  2. Read the suggestedMinterAddress from Beyond's minters endpoint.
  3. Transfer your Bitcoin L1 tokens (BRC-20, Runes...) to the suggestedMinterAddress, using either of the following methods:
    • RECOMMENDED: When submitting the token transfer tx according to the relevant standard (e.g. BRC-20 or Runes), include an additional bydTo field with the receiving wallet address on the other chain. This field will not be indexed by most platforms, but it will ensure the bridge automatically processes the incoming tx without any additional steps required.
    • ALTERNATIVE: After submitting the token transfer tx, call the Register Submitted Tx API endpoint to notify the bridge. For security, this method requires users to sign an additional (gas-free) message to verify the tx details. It also necessitates ensuring a successful API call after the message is signed. For UX simplicity, we recommend the first method whenever possible.

Parameters​

  • btcStandard — string: the Bitcoin token standard to use (BRC-20, Runes...)
  • token — string: the token symbol to bridge
  • amount — number: the amount to bridge
  • toChain — string: the destination chain
  • toAddress — string: the wallet address to receive the tokens
  • referral — string (optional): your referral's wallet address (for the Leaderboard, valid only for your first tx)

Returns​

  • Promise — string: tx ID

Example​

bridge.fromBitcoin(
  'Runes',
  'USDT',
  1000,
  'arbitrum',
  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  '0x9e03E53415D37aA96045d8dA6BF26964aF9D7eEd'
)

Bridge CHAIN → CHAIN (soon)​

info

This method is not yet available to the public. If interested in early access, please contact the Beyond team.

Move tokens between any two non-Bitcoin-L1 chains (Ethereum, Solana, Bitcoin L2s...) supported by Beyond.

bridge.betweenChains(token, amount, fromChain, toChain[, toAddress, referral])

Beyond API​

The API is an alternative way to query information about Beyond contracts, user wallets, and bridge transactions. It is useful for developers who prefer REST APIs over SDKs, or for those who want to build a fully custom integration.

Base URL​

API Endpoints​

Bitcoin L1 Token Balance

Get the Bitcoin L1 token balances (BRC-20, Runes...) of any Bitcoin address that supports inscriptions.

Path parameters

  • INSCRIPTION_ADDRESS — string: the BTC_L1 wallet address

Response

[
  {
    "id": 1124,
    "holder": "tb1qu0ndgem2nhj7v7z3c82agv4u77q8ddlz5uv05e",
    "token_symbol": "bTON",
    "token_type": "brc-20",
    "balance": "101219.669999999990",
    "balance_available": "101219.669999999990",
    "balance_transferable": "0.000000000000",
    "update_datetime": "2024-07-19T18:03:06.000Z",
    "creation_datetime": "2024-05-25T02:38:00.000Z"
  }
]
Transaction History (from any wallet)

Get the tx history of any wallet address (Bitcoin L1, Bitcoin L2s, Ethereum, Solana...) that has used the Beyond bridge previously.

You can also filter the transactions by a specific token, if desired.

  • GET — api.beyond.tech:3000/v1/q/bridge/transaction/{WALLET_ADDRESS}/{TOKEN_SYMBOL}
  • Examples:

Path parameters

  • WALLET_ADDRESS — string: the BTC_L1 or CHAIN wallet address
  • TOKEN_SYMBOL — string (optional): the token symbol

Response

[
  {
    "id": 145,
    "tx_hash": "0xcc7630af6ede82480a993fb470b4cec104f1de98c08a05dd20b262ae045511e9",
    "tx_id": 145,
    "block_height": 5972132,
    "block_timestamp": "2024-07-19T18:03:06.000Z",
    "contract_address": "0xfc753702794d05022bc36da279949d077f35d5ad",
    "op": "SendTokenToBitcoin",
    "tick": "bTON",
    "chain_id": 11155111,
    "token_address": "0x6431de5cbcb7b6cb5d7ad87115efe259e435829b",
    "token_symbol": "TONCOIN",
    "token_decimal": 18,
    "amount": "100.000000000000",
    "amount_int": "100000000000000000000",
    "from": "0x78189da8bD3332c43910BBa880dd45cEA01af74E",
    "to": "tb1qu0ndgem2nhj7v7z3c82agv4u77q8ddlz5uv05e",
    "native_fee": "30000000000000000",
    "state": "minted",
    "split_tx_id": "780ed7ae92ac03c5d18ac8b4a120fc4eebf8cb9f877897877c309931ebc78792",
    "transfer_tx_id": "ca7de9716e481916c381d49fe6388a9968387217d855f4f169ff1d411c694f72",
    "send_tx_id": "9c9426357deba26bde6e0f45832a1a4f806bc5b2dec9c2fd3bd96b95372eb8c1"
  }
]
Register Submitted Tx (optional)

As mentioned in a previous section, this API endpoint can optionally be used to notify the bridge of a BTC_L1 token transfer to a CHAIN wallet address. However, this method is less recommended due to its additional UX complexity, with the recommended approach rather being to include the bydTo field in the token transfer tx. Nevertheless, this endpoint is available for developers who prefer to use it.

  • POST method:
    • BRC-20: api.beyond.tech:3000/v1/bridge/Brc20Received
    • Runes: api.beyond.tech:3000/v1/bridge/RunesReceived

Body parameters

  • txHash — string: the Bitcoin L1 token transfer tx hash
  • tick — string: the Bitcoin L1 token symbol
  • from — string: the sender's wallet address on Bitcoin L1
  • to — string: the receiver's wallet address on the destination chain
  • amount — number: the amount of tokens transferred