Omnity

https://docs.omnity.network/docs/
Admin
Omnity is a decentralized execution layer for Bitcoin DeFi that enables Turing-complete smart...
Tokens:71,665
Snippets:268
Trust Score:6.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example: Calling get_rune_balances_for_outputs (IC CLI)

Source: https://docs.omnity.network/docs/Runes-Indexer/apis

This example demonstrates how to call the `get_rune_balances_for_outputs` function using the Internet Computer (IC) command-line interface. It shows the expected format for providing transaction outputs (outpoints) as a vector of strings and illustrates the structure of the returned data, including successful retrieval of rune balance details for each output.

```bash
Parameters: outpoint: Vec<String> (array of outpoints in format "txid: vout")
❯ dfx canister call runes-indexer get_rune_balances_for_outputs '(vec {
  "8f6ebbc114872da3ba105ce702e4793bacc1cf199940f217b38c0bd8d9bfda3a:0";
  "f43158badf8866da0b859de4bffe73c2a910996310927c72431cf486e25dd3ab:1"
})' --ic
# Returns:
(
  variant {
    Ok = vec {
      opt vec {
        record {
          confirmations = 112 : nat32;
          divisibility = 2 : nat8;
          amount = 19_000_000 : nat;
          rune_id = "840000:846";
          symbol = opt "🧧";
        };
      };
      opt vec {
        record {
          confirmations = 61 : nat32;
          divisibility = 2 : nat8;
          amount = 2_092_100 : nat;
          rune_id = "840000:846";
          symbol = opt "🧧";
        };
      };
    }
  },
)

```

--------------------------------

### TypeScript: Omnity Hub Actor Setup

Source: https://docs.omnity.network/docs/Omnity-Hub/intro

This TypeScript code sets up an actor to interact with the Omnity Hub canister. It defines the canister ID and uses `@dfinity/agent` and `@dfinity/candid` to create an actor instance based on the provided interface factory. This actor can then be used to call canister methods.

```typescript
import { Actor, HttpAgent } from "@dfinity/agent";
import { IDL } from "@dfinity/candid";
import {
  idlFactory as OmnityHubInterfaceFactory,
  _SERVICE as OmnityHubService,
} from "./OmnityHub.did";

export const OMNITY_HUB_CANISTER_ID = "7wupf-wiaaa-aaaar-qaeya-cai";

const createActor = <T>(
    canisterId: string,
    interfaceFactory: IDL.InterfaceFactory,
  ) => {
    const agent = new HttpAgent ({
      host: "https://icp0.io/",
    });
    return Actor.createActor<T>(interfaceFactory, {
      canisterId,
      agent,
    });
};

export const OmnityHub = createActor<OmnityHubService>(
    OMNITY_HUB_CANISTER_ID,
    OmnityHubInterfaceFactory,
);

```

--------------------------------

### Get Bitcoin Rune Details via Runes Indexer (Bash)

Source: https://context7.com/context7/omnity_network/llms.txt

Retrieves detailed information about a specific Bitcoin Rune using its spaced name from the Runes Indexer. This `dfx` command-line example shows how to query for Rune properties like confirmations, mints, terms, divisibility, and timestamp.

```bash
dfx canister call kzrva-ziaaa-aaaar-qamyq-cai get_rune '("HOPE•YOU•GET•RICH")' --ic

# Returns:
# (opt record {
#   confirmations = 39_825 : nat32;
#   mints = 81_000 : nat;
#   terms = opt record {
#     cap = opt (81_000 : nat);
#     height = record { opt (840_001 : nat64); opt (844_609 : nat64) };
#     offset = record { null; null };
#     amount = opt (10_000_000 : nat);
#   };
#   etching = "d66de939cb3ddb4d94f0949612e06e7a84d4d0be381d0220e2903aad68135969";
#   turbo = true;
#   premine = 0 : nat;
#   divisibility = 2 : nat8;
#   spaced_rune = "HOPE•YOU•GET•RICH";
#   number = 431 : nat64;
#   timestamp = 1_713_571_767 : nat64;
#   block = 840_000 : nat64;
#   burned = 48_537_380 : nat;
#   rune_id = "840000:846";
#   symbol = opt "🧧";
# })
```

--------------------------------

### Rust: Call Omnity Network API via HTTP

Source: https://docs.omnity.network/docs/Omnity-Hub/intro

This Rust example demonstrates calling an Omnity Network API endpoint using HTTP requests. It sets up an agent with a specified network URL and identity, encodes the arguments, sends a query to the canister, and decodes the response. Ensure you replace placeholder values like YOURPRIVATEKEY and DAPP_CANISTER_ID.

```rust
use candid::{Decode, Encode};
use ic_agent::{agent::http_transport::ReqwestTransport, export::Principal, identity::Secp256k1Identity, Agent};
use std::error::Error;
use candid::CandidType;
use thiserror::Error;
use serde::Deserialize;

#[tokio::main]
pub async fn main() -> Result<(), Box<dyn Error>> {
    let network = "https://ic0.app".to_string();

    let agent_identity = Secp256k1Identity::from_pem (
        "-----BEGIN EC PRIVATE KEY-----
        YOURPRIVATEKEY
        -----END EC PRIVATE KEY-----".as_bytes(),
    )?;

    let agent = Agent::builder()
        .with_url(network)
        .with_identity(agent_identity)
        .build()
        .map_err(|e| format!("{:?}", e))?;

    let canister_id = Principal::from_text(DAPP_CANISTER_ID.to_string())?;

    let arg: Vec<u8> = Encode!(&api_input)?;
    let ret = agent
        .query(&canister_id, "API_METHOD")
        .with_arg(arg)
        .call()
        .await?;

    let result = Decode!(&ret, API_RETURN)??;
    Ok(())
}

```

--------------------------------

### Rust: Call Omnity Network API via Canister

Source: https://docs.omnity.network/docs/Omnity-Hub/intro

This Rust code example shows how to make a cross-chain call to a canister on the Omnity Network. It utilizes `ic_cdk` and `ic_agent` for communication, specifying the target canister ID, API method, arguments, and payment in cycles. Error handling is included for the call result.

```rust
use candid::Principal;
use ic_cdk::update;

#[update]
pub async fn cross_chain_function() -> Result<(), ErrorType> {
    let cycles = 1_000_000_000;

    let bitcoin_canister_id = Principal::from_text(BTC_CANISTER_ID.to_string()).unwrap();

    let ret: (Result<(), ErrorType>,) = ic_cdk::api::call::call_with_payment128(
        bitcoin_canister_id,
        "API_METHOD",
        (args,),
        cycles,
    )
    .await
    .map_err(|err| ErrorType)?;
    ret.0
}

```

--------------------------------

### Hub - Get Chain Metas

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Retrieves metadata for all chains, with support for pagination.

```APIDOC
## GET /hub/get_chain_metas

### Description
Retrieve all chain metadata and manage pagination by providing an offset and limit.

### Method
GET

### Endpoint
/hub/get_chain_metas

### Parameters
#### Query Parameters
- **offset** (usize) - Required: Pagination offset. Specifies the number of records to skip.
- **limit** (usize) - Required: Pagination limit. Specifies the maximum number of records to return per page.

### Request Example
```json
{
  "offset": 0,
  "limit": 20
}
```

### Response
#### Success Response (200)
- **Vec<ChainMeta>** - A list of chain metadata objects, where each object contains:
  - **chain_id** (ChainId) - The unique identifier for the chain.
  - **canister_id** (String) - The canister ID associated with the chain.
  - **chain_type** (ChainType) - The type of the chain (e.g., Bitcoin, ICP).
  - **chain_state** (ChainState) - The current state of the chain.
  - **contract_address** (Option<String>) - The contract address, if applicable.
  - **counterparties** (Option<Vec<ChainId>>)- A list of connected chain IDs.
  - **fee_token** (Option<TokenId>) - The token ID used for fees on this chain.
- **Error** (string) - An error message if the operation fails.

#### Response Example (Success)
```json
{
  "result": [
    {
      "chain_id": "7wupf-wiaaa-aaaar-qaeya-cai",
      "canister_id": "OMNITY_HUB",
      "chain_type": "icp",
      "chain_state": "active",
      "contract_address": null,
      "counterparties": null,
      "fee_token": null
    },
    {
      "chain_id": "7rvjr-3qaaa-aaaar-qaeyq-cai",
      "canister_id": "OMNITY_SETTLEMENT_BITCOIN",
      "chain_type": "bitcoin",
      "chain_state": "active",
      "contract_address": "0x123...",
      "counterparties": ["icp_chain_id"],
      "fee_token": "BTC"
    }
  ]
}
```
#### Response Example (Error)
```json
{
  "error": "Failed to retrieve chain metadata"
}
```
```

--------------------------------

### GET /websites/omnity_network/token_metas

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieves all token metadata with support for pagination. You can specify an offset to start fetching from and a limit for the number of results per page.

```APIDOC
## GET /websites/omnity_network/token_metas

### Description
Retrieve all token metadata and manage pagination by providing an offset and limit.

### Method
GET

### Endpoint
`/websites/omnity_network/token_metas`

### Parameters
#### Query Parameters
- **offset** (usize) - Required - Used for pagination to specify the starting point for fetching tokens.
- **limit** (usize) - Required - Specifies the maximum number of tokens to fetch in a single call.

### Response
#### Success Response (200)
- **tokens** (Array<TokenMeta>) - A list of token metadata objects.
  - **token_id** (TokenId)
  - **name** (String)
  - **symbol** (String)
  - **issue_chain** (ChainId)
  - **decimals** (u8)
  - **icon** (Option<String>)
  - **metadata** (HashMap<String, String>)
  - **dst_chains** (Vec<ChainId>)

#### Response Example
```json
{
  "tokens": [
    {
      "token_id": "0x123...",
      "name": "Example Token",
      "symbol": "EXM",
      "issue_chain": "mainnet",
      "decimals": 18,
      "icon": "http://example.com/icon.png",
      "metadata": {"website": "http://example.com"},
      "dst_chains": ["kovan", "ropsten"]
    }
  ]
}
```

#### Error Response
- **error** (String) - An error message if the operation fails.
```

--------------------------------

### Hub - Get Token Metas

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Retrieves metadata for all tokens, with options for filtering and pagination.

```APIDOC
## GET /hub/get_token_metas

### Description
Retrieve all token metadata and manage pagination by providing an offset and limit.

### Method
GET

### Endpoint
/hub/get_token_metas

### Parameters
#### Query Parameters
- **offset** (usize) - Required: Pagination offset. Specifies the number of records to skip.
- **limit** (usize) - Required: Pagination limit. Specifies the maximum number of records to return per page.

### Request Example
```json
{
  "offset": 0,
  "limit": 50
}
```

### Response
#### Success Response (200)
- **Vec<TokenMeta>** - A list of token metadata objects, where each object contains:
  - **token_id** (TokenId) - The unique identifier for the token.
  - **name** (String) - The name of the token.
  - **symbol** (String) - The symbol of the token.
  - **issue_chain** (ChainId) - The chain ID where the token was issued.
  - **decimals** (u8) - The number of decimal places for the token.
  - **icon** (Option<String>) - URL to the token's icon, if available.
  - **metadata** (HashMap<String, String>) - Additional metadata for the token.
  - **dst_chains** (Vec<ChainId>) - A list of chain IDs where this token can be transferred.
- **Error** (string) - An error message if the operation fails.

#### Response Example (Success)
```json
{
  "result": [
    {
      "token_id": "BTC",
      "name": "Bitcoin",
      "symbol": "BTC",
      "issue_chain": "Bitcoin",
      "decimals": 8,
      "icon": "https://example.com/btc.png",
      "metadata": {"description": "Decentralized digital currency"},
      "dst_chains": ["icp_chain_id", "ethereum_chain_id"]
    }
  ]
}
```
#### Response Example (Error)
```json
{
  "error": "Failed to retrieve token metadata"
}
```
```

--------------------------------

### Get Token List

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieves a list of all available tokens on the Bitcoin network.

```APIDOC
## GET /get_token_list

### Description
Retrieve a list of tokens available on the bitcoin network.

### Method
GET

### Endpoint
/get_token_list

### Parameters
None

### Response
#### Success Response (200)
- **tokens** (Array<TokenResp>) - A list of tokens.
  - **token_id** (TokenId) - The ID of the token.
  - **symbol** (String) - The symbol of the token.
  - **decimals** (u8) - The number of decimals for the token.
  - **icon** (Option<String>) - URL of the token's icon.
  - **rune_id** (Option<String>) - The ID of the rune associated with the token.

#### Response Example
```json
{
  "tokens": [
    {
      "token_id": "1",
      "symbol": "BTC",
      "decimals": 8,
      "icon": "https://example.com/btc.png",
      "rune_id": "1"
    }
  ]
}
```
```

--------------------------------

### GET /fees

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieves a list of fees, with options to filter by chain or token ID, and manage pagination.

```APIDOC
## GET /fees

### Description
Specify filters to narrow down the list of fees based on the either ChainId or TokenId and manage pagination by providing an offset and limit.

### Method
GET

### Endpoint
/fees

### Query Parameters
- **chain_id** (ChainId) - Optional - Filters fees by the chain.
- **token_id** (TokenId) - Optional - Filters fees by the token.
- **offset** (usize) - Required - The starting index for pagination.
- **limit** (usize) - Required - The maximum number of results to return.

### Response
#### Success Response (200)
- **fees** (Vec<(ChainId, TokenId, u128)>) - A list of tuples, each containing chain ID, token ID, and the fee amount.

#### Response Example
```json
{
  "fees": [
    ["some_chain_id", "some_token_id", 1000000]
  ]
}
```
```

--------------------------------

### Get RichSwap Pool List

Source: https://context7.com/context7/omnity_network/llms.txt

Retrieves a list of all available liquidity pools within the RichSwap exchange. It supports pagination with 'from' and 'limit' parameters.

```bash
dfx canister call kmwen-yaaaa-aaaar-qam3a-cai get_pool_list '(record {from=null;limit=100;},)' --ic

# Returns: vec { record { name = "HOPE•YOU•GET•RICH"; address = "bc1p..." } }
```

--------------------------------

### Create New Project with dfx Tool

Source: https://docs.omnity.network/docs/REE/first-exchange

This command initializes a new project structure for a REE DApp, including a Rust backend canister and a React frontend. It requires the DFINITY Canister SDK (dfx) to be installed.

```bash
dfx new --type rust --frontend react ree-demo-exchange  

```

--------------------------------

### GET /get_txs

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieve all historical transactions from the start, paginated by offset and limit.

```APIDOC
## GET /get_txs

### Description
Retrieve all historical transactions from the start, paginated by offset and limit.

### Method
GET

### Endpoint
/get_txs

### Parameters
#### Query Parameters
- **offset** (usize) - Required - The offset for pagination. Specifies where to start fetching tickets from.
- **limit** (usize) - Required - The limit for pagination. Specifies the maximum number of tickets to fetch in a single call.

### Response
#### Success Response (200)
- **tickets** (Vec<Ticket>) - A list of transaction tickets.
  - **ticket_id** (TicketId)
  - **ticket_type** (TicketType)
  - **ticket_time** (Timestamp)
  - **src_chain** (ChainId)
  - **dst_chain** (ChainId)
  - **action** (TxAction)
  - **token** (TokenId)
  - **amount** (String)
  - **sender** (Account) - Optional
  - **receiver** (Account)
  - **memo** (Vec<u8>) - Optional

#### Error Response (e.g., 400, 500)
- **error** (String) - An error message if the operation fails.
```

--------------------------------

### Query Pool List from RichSwap (IC P)

Source: https://docs.omnity.network/docs/Rich-Swap/guide

This command fetches the list of available pools from the RichSwap canister. It requires access to an ICP canister and uses the dfx command-line tool. The output is a list of pools, which can be used for subsequent swap operations.

```shell
# fetch the pool list  
dfx canister call kmwen-yaaaa-aaaar-qam3a-cai --ic get_pool_list '(record {from=null;limit=100;},)'  

```

--------------------------------

### Initialize Demo Lending Pool (Rust)

Source: https://docs.omnity.network/docs/REE/first-exchange

Initializes a demonstration lending pool for the exchange. This function is restricted to the canister's controller and requests a pool address from the REE system. It then stores the pool with an empty state in the LENDING_POOLS storage.

```rust
use ic_cdk::api::caller;
use ic_cdk::api::is_controller;

// Assuming CoinId, CoinMeta, request_ree_pool_address, Network, and crate::Pool are defined elsewhere
// Assuming crate::SCHNORR_KEY_NAME and crate::LENDING_POOLS are defined elsewhere

#[update]
// init_pool creates a demonstration lending pool when the exchange is deployed
// This pool allows users to borrow BTC satoshis at a 1:1 ratio by depositing RICH tokens as collateral
async fn init_pool() -> Result<(), String> {
    let caller = ic_cdk::api::caller();
    if !ic_cdk::api::is_controller(&caller) {
        return Err("Not authorized".to_string());
    }

    let id = CoinId::rune(72798, 1058);
    let meta = CoinMeta {
        id,
        symbol: "HOPE•YOU•GET•RICH".to_string(),
        min_amount: 1,
    };
    // Request a pool address from the REE system
    let (untweaked, _, addr) = request_ree_pool_address(
        crate::SCHNORR_KEY_NAME,
        vec![id.to_string().as_bytes().to_vec()],
        Network::Testnet4,
    )
    .await?;

    // Initialize the pool with empty state
    let pool = crate::Pool {
        meta,
        pubkey: untweaked.clone(),
        addr: addr.to_string(),
        states: vec![],
    };
    // Store the pool in the LENDING_POOLS storage
    crate::LENDING_POOLS.with_borrow_mut(|p| {
        p.insert(addr.to_string(), pool);
    });
    Ok(())
}

```

--------------------------------

### GET /get_chain_size

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Get the total number of chains on Omnity.

```APIDOC
## GET /get_chain_size

### Description
Get the total number of chains on Omnity.

### Method
GET

### Endpoint
/get_chain_size

### Parameters
None

### Response
#### Success Response (200)
- **chain_count** (u64) - The total number of chains.

#### Error Response (e.g., 400, 500)
- **error** (String) - An error message if the operation fails.
```

--------------------------------

### CLI Command for Donation

Source: https://docs.omnity.network/docs/Rich-Swap/apis

This command-line interface command provides an example of how to execute a donation using the donate-cli tool. It requires the pool address, user's private key, RPC URL, and network type.

```bash
./target/debug/donate-cli \
  --pool-address tb1puzk3gn4z3rrjjnrhlgk5yvts8ejs0j2umazpcc4anq62wfk00e6ssw9p0n \
  --input-priv-key {your_private_key} \
  --rpc-url $BTC_RPC_URL \
  --network testnet
```

--------------------------------

### GET /websites/omnity_network/token_size

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Gets the total number of tokens currently on the Omnity network.

```APIDOC
## GET /websites/omnity_network/token_size

### Description
Get the total number of tokens on Omnity.

### Method
GET

### Endpoint
`/websites/omnity_network/token_size`

### Response
#### Success Response (200)
- **count** (u64) - The total number of tokens on the Omnity network.

#### Response Example
```json
{
  "count": 15000
}
```

#### Error Response
- **error** (String) - An error message if the operation fails.
```

--------------------------------

### get_token_ledger

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Get the token ledger canister ID based on token_id.

```APIDOC
## get_token_ledger

### Description
Get the token ledger canister ID based on token_id.

### Method
GET

### Endpoint
/websites/omnity_network/eicp/get_token_ledger

### Parameters
#### Query Parameters
- **token_id** (String) - Required - The ID of the token.

### Response
#### Success Response (200)
- **canister_id** (Principal) - The token ledger canister ID, or null if not found.

### Response Example
```json
{
  "canister_id": "<principal>"
}
```
```

--------------------------------

### Obtain Quote from RichSwap Pool (dfx CLI)

Source: https://docs.omnity.network/docs/Rich-Swap/guide

This command uses the dfx CLI to call the `pre_swap` function on the specified canister to obtain a quote for a token swap. It specifies the pool address and the input coin details (BTC with a value of 10000 sats). The response contains the pool's offer, including the output amount, nonce, price impact, and input UTXO details.

```bash
dfx canister call kmwen-yaaaa-aaaar-qam3a-cai --ic pre_swap '("bc1ptnxf8aal3apeg8r4zysr6k2mhadg833se2dm4nssl7drjlqdh2jqa4tk3p", record {id="0:0"; value=10000;})'
```

--------------------------------

### Rust: Prepare Deposit Transaction with pre_deposit

Source: https://docs.omnity.network/docs/REE/first-exchange

The `pre_deposit` function queries necessary information for constructing a deposit transaction. It takes the pool address and deposit amount, validates the amount against the minimum requirement, and returns the pool's UTXO and nonce if valid. It's written in Rust.

```rust
#[query]  
// pre_deposit queries the information needed to build a deposit transaction  
// by specifying the target pool address and deposit amount  
pub fn pre_deposit(  
    pool_address: String,  
    amount: CoinBalance,  
) -> Result<DepositOffer, ExchangeError> {  
    if amount.value < CoinMeta::btc().min_amount {  
        return Err(ExchangeError::TooSmallFunds);  
    }  
    let pool = crate::get_pool(&pool_address).ok_or(ExchangeError::InvalidPool)?;  
    let state = pool.states.last().clone();  
    Ok(DepositOffer {  
        pool_utxo: state.map(|s| s.utxo.clone()).flatten(),  
        nonce: state.map(|s| s.nonce).unwrap_or_default(),  
    })  
}  

```

--------------------------------

### dfx CLI: Call get_rune Query

Source: https://docs.omnity.network/docs/Runes-Indexer/apis

Example of calling the `get_rune` query on the Runes Indexer canister using the dfx command-line interface. This demonstrates how to pass a spaced rune name and the expected detailed output for a rune entry, including confirmations, mints, terms, and more.

```bash
#!/bin/bash
dfx canister call runes-indexer get_rune '("HOPE•YOU•GET•RICH")' --ic
```

--------------------------------

### Invoke RichSwap Transaction (dfx CLI)

Source: https://docs.omnity.network/docs/Rich-Swap/guide

This command uses the dfx CLI to call the `invoke` function on the specified canister to execute a pre-arranged swap transaction. The `...` placeholder indicates that the actual arguments, derived from the PSBT and IntentionSet structure, should be provided here. This function broadcasts the signed transaction to the BTC network via REE.

```bash
dfx canister call kqs64-paaaa-aaaar-qamza-cai --ic invoke '...'
```

--------------------------------

### Constructing and Invoking Deposit IntentionSet (React)

Source: https://docs.omnity.network/docs/REE/first-exchange

This React JavaScript function demonstrates how to construct an `IntentionSet` for a deposit action and invoke the Orchestrator's `execute_tx` method. It includes steps for obtaining a signed PSBT from the user's wallet, defining the deposit intention with relevant parameters like exchange ID, pool address, and UTXO details, and handling success or failure responses. It requires a PSBT object, deposit offer details, and external functions like `signPsbt` and `Orchestrator.invoke`.

```javascript
const onSubmit = async () => {
  if (!psbt || !depositOffer) { // Ensure PSBT and pre_deposit info exist
    return;
  }
  setIsSubmiting(true);
  try {
    // Get the signed PSBT hex from the user's wallet
    const psbtBase64 = psbt.toBase64();
    const res = await signPsbt(psbtBase64); // Wallet signing function
    const signedPsbtHex = res?.signedPsbtHex ?? "";
    if (!signedPsbtHex) throw new Error("Signing Failed");

    // Construct the IntentionSet
    const intentionSet = {
      tx_fee_in_sats: fee, // Calculated fee
      initiator_address: paymentAddress, // User's address
      intentions: [
        {
          action: "deposit",
          exchange_id: EXCHANGE_ID, // Your Exchange Canister ID
          input_coins: inputCoins, // User's BTC input
          pool_utxo_spend: [], // Pool spends nothing in simple deposit
          pool_utxo_receive: poolReceiveOutpoints, // Expected pool output
          output_coins: [], // No other outputs in simple deposit
          pool_address: pool.address,
          action_params: "",
          nonce: depositOffer.nonce, // Nonce from pre_deposit
        },
      ],
    };

    // Call the Orchestrator's invoke method
    const txid = await Orchestrator.invoke({
      intention_set: intentionSet,
      psbt_hex: signedPsbtHex,
    });

    // Handle success (e.g., update UI, track spent UTXOs)
    addSpentUtxos(toSpendUtxos);
    onSuccess(txid);

  } catch (error: any) {
    // Handle errors (e.g., user rejection, network issues)
    if (error.code !== 4001) { // Ignore user wallet rejection
      console.error(error);
      toast(error.toString());
    }
  } finally {
    setIsSubmiting(false);
  }
};

```

--------------------------------

### Hub - Get Token Position Size

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Retrieves the total amount of each token across all chains.

```APIDOC
## GET /hub/get_token_position_size

### Description
Get the length of the list that contains the total amount of each token on every chain.

### Method
GET

### Endpoint
/hub/get_token_position_size

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **u64** (u64) - the total amount of each token on every chain
- **Error** (string) - an error message as a string will be returned if the operation fails

#### Response Example
```json
{
  "result": 12345 // Example success response
}
```
#### Error Response Example
```json
{
  "error": "Operation failed"
}
```
```

--------------------------------

### Frontend: Call pre_deposit Query Method (React useEffect)

Source: https://docs.omnity.network/docs/REE/first-exchange

This snippet demonstrates how to call the `pre_deposit` query method on an Exchange canister from a React frontend. It uses a `useEffect` hook to trigger the call when the input amount changes, processes the response to store deposit offers, and includes basic error handling and loading state management. It depends on a `debouncedInputAmount`, `parseCoinAmount` function, and `BITCOIN` constants.

```typescript
useEffect(() => {
  if (!Number(debouncedInputAmount)) {
    return;
  }
  const btcAmount = parseCoinAmount(debouncedInputAmount, BITCOIN);
  setIsQuoting(true);
  // Call the exchange canister's pre_deposit method
  lendingActor
    .pre_deposit(pool.address, { id: BITCOIN.id, value: BigInt(btcAmount) })
    .then((res: any) => {
      if (res.Ok) {
        // Store the returned offer (pool UTXO, nonce)
        setDepositOffer(res.Ok);
      }
    })
    .finally(() => {
      setIsQuoting(false);
    });
}, [debouncedInputAmount]); // Re-run when amount changes
```

--------------------------------

### GET /get_chain_metas

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieve all chain metadata, paginated by offset and limit.

```APIDOC
## GET /get_chain_metas

### Description
Retrieve all chain metadata, paginated by offset and limit.

### Method
GET

### Endpoint
/get_chain_metas

### Parameters
#### Query Parameters
- **offset** (usize) - Required - The offset for pagination. Specifies where to start fetching chain metadata from.
- **limit** (usize) - Required - The limit for pagination. Specifies the maximum number of chain metadata entries to fetch in a single call.

### Response
#### Success Response (200)
- **chain_metas** (Vec<ChainMeta>) - A list of chain metadata.
  - **chain_id** (ChainId)
  - **canister_id** (String)
  - **chain_type** (ChainType)
  - **chain_state** (ChainState)
  - **contract_address** (String) - Optional
  - **counterparties** (Vec<ChainId>) - Optional
  - **fee_token** (TokenId) - Optional

#### Error Response (e.g., 400, 500)
- **error** (String) - An error message if the operation fails.
```

--------------------------------

### IntentionSet and InvokeArgs Data Structures (Motoko)

Source: https://docs.omnity.network/docs/Rich-Swap/guide

These are Motoko type definitions for the parameters required by the `invoke` function. `IntentionSet` defines the overall transaction details including fee, initiator, and a list of intentions. `Intention` specifies individual swap actions with input/output coins, action type, exchange details, and pool information. `InvokeArgs` bundles the `IntentionSet` with initiator UTXO proof and the PSBT in hexadecimal format.

```motoko
type Intention = record {
  input_coins : vec InputCoin;
  output_coins : vec OutputCoin;
  action : text;
  exchange_id : text;
  action_params : text;
  nonce : nat64;
  pool_address : text;
  pool_utxo_spent : vec text;
  pool_utxo_received : vec Utxo;
};

type IntentionSet = record {
  tx_fee_in_sats : nat64;
  initiator_address : text;
  intentions : vec Intention;
};

type InvokeArgs = record {
  intention_set : IntentionSet;
  initiator_utxo_proof : blob;
  psbt_hex : text;
};
```

--------------------------------

### Hub - Get Token Size

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Retrieves the total count of unique tokens available on the Omnity network.

```APIDOC
## GET /hub/get_token_size

### Description
Get the total number of tokens on Omnity.

### Method
GET

### Endpoint
/hub/get_token_size

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **u64** (u64) - the total number of tokens
- **Error** (string) - an error message as a string will be returned if the operation fails

#### Response Example
```json
{
  "result": 150 // Example: 150 unique tokens
}
```
#### Error Response Example
```json
{
  "error": "Failed to get token size"
}
```
```

--------------------------------

### Get Rune Balances for UTXOs via Runes Indexer (Bash)

Source: https://context7.com/context7/omnity_network/llms.txt

Retrieves Bitcoin Rune balances for specified transaction outputs (UTXOs) using the Runes Indexer. This `dfx` command demonstrates how to query for Rune balance details, including confirmations, divisibility, amount, rune ID, and symbol for each provided UTXO.

```bash
dfx canister call kzrva-ziaaa-aaaar-qamyq-cai get_rune_balances_for_outputs '(vec {
  "8f6ebbc114872da3ba105ce702e4793bacc1cf199940f217b38c0bd8d9bfda3a:0";
  "f43158badf8866da0b859de4bffe73c2a910996310927c72431cf486e25dd3ab:1"
})' --ic

# Returns:
# (variant {
#   Ok = vec {
#     opt vec {
#       record {
#         confirmations = 112 : nat32;
#         divisibility = 2 : nat8;
#         amount = 19_000_000 : nat;
#         rune_id = "840000:846";
#         symbol = opt "🧧";
#       };
#     };
#     opt vec {
#       record {
#         confirmations = 61 : nat32;
#         divisibility = 2 : nat8;
#         amount = 2_092_100 : nat;
#         rune_id = "840000:846";
#         symbol = opt "🧧";
#       };
#     };
#   }
# })
```

--------------------------------

### Hub - Get Chain Size

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Retrieves the total number of chains currently registered on the Omnity network.

```APIDOC
## GET /hub/get_chain_size

### Description
Get the total number of chains on Omnity.

### Method
GET

### Endpoint
/hub/get_chain_size

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **u64** (u64) - the total number of chains
- **Error** (string) - an error message as a string will be returned if the operation fails

#### Response Example
```json
{
  "result": 50 // Example: 50 chains on Omnity
}
```
#### Error Response Example
```json
{
  "error": "Failed to get chain size"
}
```
```

--------------------------------

### Hub - Get Chain Tokens

Source: https://docs.omnity.network/docs/Omnity-Hub/explorer

Retrieves a list of tokens on a specific chain, with options for filtering and pagination.

```APIDOC
## GET /hub/get_chain_tokens

### Description
Specify filters to narrow down the list of token amount on a chain based on the either ChainId or TokenId and manage pagination by providing an offset and limit.

### Method
GET

### Endpoint
/hub/get_chain_tokens

### Parameters
#### Query Parameters
- **chain_id** (Option<ChainId>) - Optional: Filters tokens by chain ID.
- **token_id** (Option<TokenId>) - Optional: Filters tokens by token ID.
- **offset** (usize) - Required: The number of records to skip for pagination.
- **limit** (usize) - Required: The maximum number of records to return for pagination.

### Request Example
```json
{
  "chain_id": "your_chain_id",
  "token_id": "your_token_id",
  "offset": 0,
  "limit": 10
}
```

### Response
#### Success Response (200)
- **Vec<TokenOnChain>** - a vector of token objects on the specified chain, where each object contains:
  - **chain_id** (ChainId) - The ID of the chain.
  - **token_id** (TokenId) - The ID of the token.
  - **amount** (u128) - The amount of the token.
- **Error** (string) - an error message as a string will be returned if the operation fails

#### Response Example (Success)
```json
{
  "result": [
    {
      "chain_id": "chain1",
      "token_id": "tokenA",
      "amount": 1000000
    },
    {
      "chain_id": "chain1",
      "token_id": "tokenB",
      "amount": 500000
    }
  ]
}
```
#### Response Example (Error)
```json
{
  "error": "Failed to retrieve chain tokens"
}
```
```

--------------------------------

### dfx CLI: Call get_etching Query

Source: https://docs.omnity.network/docs/Runes-Indexer/apis

Example of calling the `get_etching` query on the Runes Indexer canister using the dfx command-line interface. This demonstrates how to pass a transaction ID and the expected format of the returned data, including confirmation count and rune ID.

```bash
#!/bin/bash
dfx canister call runes-indexer get_etching '("d66de939cb3ddb4d94f0949612e06e7a84d4d0be381d0220e2903aad68135969")' --ic
```

--------------------------------

### GET /websites/omnity_network/pending_ticket_size

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieves the total count of pending tickets on the Omnity network.

```APIDOC
## GET /websites/omnity_network/pending_ticket_size

### Description
Get the total number of pending tickets on Omnity.

### Method
GET

### Endpoint
`/websites/omnity_network/pending_ticket_size`

### Response
#### Success Response (200)
- **count** (u64) - The number of pending tickets.

#### Response Example
```json
{
  "count": 500
}
```

#### Error Response
- **error** (String) - An error message if the operation fails.
```

--------------------------------

### Rust: IntentionSet structure for transaction goals

Source: https://docs.omnity.network/docs/REE/first-exchange

Represents the overall goal of a transaction, including the initiator's address for refunds, the proposed transaction fee in SATs, and a list of specific intentions. Each intention details actions within a target exchange, parameters, pool information, nonces, and involved UTXOs or coins.

```rust
// Defines the overall goal of the transaction
pub struct IntentionSet {
    pub initiator_address: String,
    pub tx_fee_in_sats: u64,
    pub intentions: Vec<Intention>,
}

// Defines a single action within the transaction
pub struct Intention {
    pub exchange_id: String,
    pub action: String,
    pub action_params: String,
    pub pool_address: String,
    pub nonce: u64,
    pub pool_utxo_spend: Vec<String>,
    pub pool_utxo_receive: Vec<String>,
    pub input_coins: Vec<InputCoin>,
    pub output_coins: Vec<OutputCoin>,
}

// Represents coins being spent
pub struct InputCoin {

```

--------------------------------

### ICP CLI Commands for Rune Operations

Source: https://docs.omnity.network/docs/Omnity-Hub/runes

This snippet provides command-line examples using `dfx` to interact with ICP canisters for managing runes. It covers retrieving token lists, checking redeem fees, approving token transfers for fees, and invoking the `generate_ticket_v2` method for cross-chain rune transactions. Ensure necessary approvals and fee transfers are completed before invocation.

```bash
# Retrieve a list of token_ids and ledger principals available on icp.  
❯ dfx canister call icp_route get_token_list --ic  

#  Retrieve the redeem fee information：  
❯ dfx canister call icp_route get_redeem_fee '("Bitcoin")' --ic  

# Approve icp(ryjl3-tyaaa-aaaaa-aaaba-cai:for redeem fees) & icrc token(e.g,:$Rich(77xez-aaaaa-aaaar-qaezq-cai)) by call the icrc2_approve method of the icp canister to authorize our canister (7ywcn-nyaaa-aaaar-qaeza-cai) to spend the transaction fee. Please ensure the transfer fee is deducted before approving the full balance.  
❯ dfx canister call icp_ledger icrc2_approve '(record { spender=record { owner=principal "7ywcn-nyaaa-aaaar-qaeza-cai" } ; amount=60_010_000;   } )' --ic  
❯ dfx canister call rich_ledger icrc2_approve '(record { spender=record { owner=principal "7ywcn-nyaaa-aaaar-qaeza-cai" } ; amount=100000;   } )' --ic  

# Invoke the generate_ticket_v2 method:  
❯  dfx canister call icp_route generate_ticket_v2 '(record { target_chain_id="Bitcoin"; receiver="bc1q55ghpce6jq8q78cfcnmkz8qq5ww3asd28dw"; token_id="Bitcoin-runes-HOPE•YOU•GET•RICH"; amount=100000; from_subaccount=null; action=variant { Redeem}  } )' --ic  
```

--------------------------------

### GET /tx/{ticket_id}

Source: https://docs.omnity.network/docs/Omnity-Hub/runes_on_bitcoin

Retrieves the metadata for a transaction using its Ticket ID.

```APIDOC
## GET /tx/{ticket_id}

### Description
Retrieve the metadata for the transaction using the TicketId.

### Method
GET

### Endpoint
/tx/{ticket_id}

### Path Parameters
- **ticket_id** (TicketId) - Required - The unique identifier of the transaction ticket.

### Response
#### Success Response (200)
- **transaction** (Ticket) - A ticket object containing transaction metadata.
  - **ticket_id** (TicketId) - The unique identifier for the ticket.
  - **ticket_type** (TicketType) - The type of the ticket.
  - **ticket_time** (Timestamp) - The timestamp of the ticket.
  - **src_chain** (ChainId) - The source chain ID.
  - **dst_chain** (ChainId) - The destination chain ID.
  - **action** (TxAction) - The action performed by the transaction.
  - **token** (TokenId) - The identifier of the token involved.
  - **amount** (String) - The amount of the token.
  - **sender** (Option<Account>) - The sender's account, if available.
  - **receiver** (Account) - The receiver's account.
  - **memo** (Option<Vec<u8>>) - The memo associated with the transaction, if any.

#### Response Example
```json
{
  "transaction": {
    "ticket_id": "some_ticket_id",
    "ticket_type": "Transfer",
    "ticket_time": 1678886400,
    "src_chain": "chain_a",
    "dst_chain": "chain_b",
    "action": "Send",
    "token": "token_x",
    "amount": "1000000000000000000",
    "sender": {"address": "sender_address"},
    "receiver": {"address": "receiver_address"},
    "memo": null
  }
}
```
```
Tokens:
Raw