1. The token contract address is the only identifier, not the name!
   • Even if two tokens are both named

     USDT

     , as long as their contract addresses differ (for example, one is a bridged version

     0xd96a...

     and the other is native USDT(Native)

     0x4806...

     ), they are two different assets on-chain.
   • Swapping same-name tokens on the same chain (e.g. Celo USDT -> Celo USDT(Native)) is absolutely feasible and a very common DeFi need. Do NOT tell users “same currency cannot be exchanged”, “has no real value”, or refuse to execute.
2. The real reason behind the API error

   Same currency cannot be exchanged

   • This error is NOT because “the protocol does not support USDT to USDT(Native)”.
   • The real reason is: a parameter assembly bug caused the

     fromTokenAddress

     and

     toTokenAddress

     you sent to the Bridgers API to become exactly the same contract address.
   • Solution: Inspect the name-matching logic in the code to ensure that symbols like

     USDT(Native)

     (with parentheses or special casing) are correctly mapped to different contract addresses.
   • Path: for native tokens, please look them up in

     assets/omni-bridgers-tokens.json

     .
3. The real reason behind the API error

   Service Internal Error (999)

   • This is usually due to missing implicit parameters that Bridgers strictly validates.
   • Must include:

     sourceType: "H5"

     ,

     sourceFlag: "perpex01"

     , and

     equipmentNo

     must be filled with the user’s real wallet address, not left empty. Otherwise the API will reject it.
4. Cross-chain / swap operations must upload the tx hash
   • After the on-chain

     swap

     transaction is successfully mined, you must call

     /api/exchangeRecord/updateDataAndStatus

     to send

     tx.hash

     back to the server.
   • If you don’t send it back, the remote side cannot reconcile in time and user funds may get stuck.

• ✅ Market orders (Market) - execute immediately
• ✅ Limit orders (Limit) - execute when price reaches the specified level
• ✅ Stop-loss / take-profit (Stop Loss / Take Profit) - automatically execute when price is triggered
• ✅ TWAP split orders - split large orders into smaller ones; use multicall, single tx hash
• ✅ Add / remove liquidity - deposit long/short tokens to receive market tokens, or redeem them
• ✅ Position query - view position state in real time
• ✅ Market browsing - view all available trading pairs
• ✅ Omni Bridge cross-chain deposit/withdrawal - via Omni Bridge, move assets into/out of Celo
• ✅ Bridgers cross-chain swap - cross-chain token swaps via Bridgers (e.g. Arbitrum USDC → Celo USDT)

• Open long position: acceptablePrice = oraclePrice × 1.03 (+3%)
• Open short position: acceptablePrice = oraclePrice × 0.97 (-3%)
• Close long position: acceptablePrice = oraclePrice × 0.97 (-3%)
• Close short position: acceptablePrice = oraclePrice × 1.03 (+3%)

• Default executionFee: 0.2 CELO
• Can be customized via

  executionFeeHuman

  in the order config

sendTokens

createDeposit

sendTokens

createWithdrawal

assets/addresses.json

celo

• DepositVault

  - deposit contract address

• WithdrawalVault

  - withdrawal contract address

• WNT

  - execution-fee token address (usually wrapped native token on Celo)

1. Add: user approves → multicall(sendTokens × 3 + createDeposit) → keeper executes → receive market tokens
2. Remove: user approves → multicall(sendTokens × 2 + createWithdrawal) → keeper executes → receive long/short tokens

• Omni Bridge: Cross-chain bridge infrastructure used to transfer representations of the same asset between chains (e.g. from Ethereum to Celo).
• Role of this Skill:
  • Does not reimplement complex frontend quoting, route selection, or fee estimation logic in this repo;
  • Only provides a TX sender based on transaction data generated by a frontend/backend, so you can perform the same cross-chain action from a pure CLI environment.

• You obtain the parameters of an Omni Bridge transaction (

  to

  ,

  data

  ,

  value

  , etc.) from any frontend or its backend API and want to execute it directly on a server / terminal;
• You already have a stable routing service to generate bridge transactions, and only need a reliable “sign and broadcast” script.

1. Select source and destination chains (for example: Ethereum → Celo).
2. Select deposit/withdraw asset and amount:
   • Choose the token to send from the source chain (

     fromToken

     );
   • Choose the token to receive on the destination chain (

     toToken

     );
   • Enter the amount; the frontend uses

     bridgersFetcher

     or similar APIs to get quotes and min/max amounts.
3. Check balance and allowance:
   • The frontend checks current token balance;
   • For ERC20 tokens, it checks allowance; if insufficient, it sends an Approve transaction first.
4. Generate Omni Bridge transaction data:
   • The frontend calls the routing service and obtains the on-chain transaction details:

     • to

       : Omni Bridge or aggregator contract address

     • data

       : call data (ABI-encoded)

     • value

       : value of native asset to send, if any
5. Send on-chain transaction:
   • The frontend sends the transaction via a wallet (e.g. MetaMask).
6. Wait for cross-chain completion:
   • Listen for confirmation of the source chain transaction;
   • After bridging completes, check balance or records on the destination chain.

• In

  assets/celo.env.local

  , configure:

CELO_RPC_URL=your_CELO_RPC_url
CELO_PRIVATE_KEY=your_wallet_private_key
CELO_CHAIN_ID=42220 # or the corresponding Celo chain ID

Note: if you want to send Omni Bridge transactions on another chain, temporarily change the above environment variables to that chain’s RPC/private key/ChainId. The script itself only depends on the RPC and is not tightly bound to Celo.

node scripts/omni-bridge-tx.js \
  --to 0xBridgeOrRouterAddress \
  --data 0xYourCalldataHere \
  --value 0 \
  --gasLimit 600000

• Required parameters

  • --to

    : transaction recipient address (typically the Omni Bridge/router contract)

  • --data

    : ABI-encoded call data
• Optional parameters

  • --value

    : amount of native token to send (string, in ETH/CELO units, e.g.

    0

    or

    0.1

    )

  • --gasLimit

    : custom gas limit (defaults to

    ethers

    estimate)

1. Reads

   CELO_RPC_URL

   ,

   CELO_PRIVATE_KEY

   ,

   CELO_CHAIN_ID

   from

   assets/celo.env.local

   ;
2. Creates a Provider and Wallet via

   ethers

   ;
3. Constructs and sends the transaction using the provided

   to

   ,

   data

   , and

   value

   ;
4. Prints:
   • The sending wallet address
   • The transaction hash
   • Block number and gas usage once confirmed

• Intercepting wallet calls in the browser devtools;
• Or using the

  tx

  data returned by the project’s routing/bridge API (e.g.

  { to, data, value }

  ).

node scripts/omni-bridge-tx.js \
  --to 0xYourOmniBridgeAddress \
  --data 0xabcdef1234... \
  --value 0.05

• Cross-chain deposit: deposit assets from the current chain into Omni Bridge and wait to receive tokens on the destination chain;
• Cross-chain withdrawal: withdraw assets from a bridge contract to the current or another chain.

bridgersFetcher

https://api.bridgers.xyz

1. The frontend constructs

   params

   (see

   submitHandle

   in

   DepositView.tsx

   /

   WithdrawalView.tsx

   ):

   • equipmentNo

     /

     fromAddress

     /

     toAddress

     : user address

   • fromTokenAddress

     /

     toTokenAddress

     : source/destination token addresses (use placeholder

     0xeeee...

     for native tokens)

   • fromTokenChain

     /

     toTokenChain

     : chain identifiers (e.g.

     ETH

     ,

     CELO

     , taken from token config

     mainNetwork

     )

   • fromTokenAmount

     : amount on the source chain (on-chain precision or API format)

   • amountOutMin

     : minimum acceptable output

   • fromCoinCode

     /

     toCoinCode

     : token symbols (e.g.

     USDT

     ,

     USDC

     )
2. The frontend calls

   bridgersFetcher.fetchSwapCall(params)

   :

// Pseudocode example: bridgersFetcher
export class bridgersFetcher {
  fetchSwapCall(params) {
    return fetch(buildUrl('https://api.bridgers.xyz', '/api/sswap/swap'), {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(params),
    }).then((res) => res.json())
  }
}

1. On success, the response structure contains

   data.txData

   :

// Typical snippet from DepositView / WithdrawalView
const calldata = await bridgers.fetchSwapCall(params)
if (calldata.resCode === 100) {
  const txData = calldata.data.txData
  // txData structure roughly:
  // {
  //   to:   "0x...", // target bridge/router contract address
  //   data: "0x...", // ABI-encoded calldata
  //   value:"0x..."  // optional, hex string amount
  // }
}

txData

txData

node scripts/omni-bridge-tx.js \
  --to   "$(jq -r '.data.txData.to'   bridgers-tx.json)" \
  --data "$(jq -r '.data.txData.data' bridgers-tx.json)" \
  --value "0"  # If txData.value is non-zero, put the corresponding ETH/CELO amount here

• txData.value

  is usually a hex string (Wei). The

  --value

  parameter of

  omni-bridge-tx.js

  uses human-readable units and parses them with

  parseEther

  . If you need to match

  txData.value

  exactly, you can:
  • Modify

    omni-bridge-tx.js

    to support hex strings directly; or
  • Convert hex Wei to ETH/CELO in an external script, then pass the result to

    --value

    .

1. Use the Bridgers REST API to generate a cross-chain bridge transaction (

   /api/sswap/swap

   →

   txData

   );
2. Use this repo’s

   omni-bridge-tx.js

   to sign and send the Omni Bridge deposit/withdrawal transaction from the CLI;
3. Optionally integrate

   bridgers.updateDataAndStatus

   or

   fetchTransData

   APIs on the server to sync order status.

• When storing a private key in

  assets/celo.env.local

  , ensure the file is never committed to version control and has restricted read permissions on the server.
• Before execution, always verify:

  • --to

    address is correct;

  • --data

    comes from a trusted frontend/backend service;

  • --value

    is within an acceptable risk amount.
• If unsure, test with a very small amount (e.g. 0.001).

1. User creates order → call

   createOrder

   to submit the order
2. Keeper listens → off-chain keeper listens for order events
3. Keeper executes → provides prices and executes the order
4. Order completes → position is updated and funds change

• Ensure the wallet has enough CELO to pay gas and executionFee
• Ensure sufficient collateral token balance
• Limit/stop orders may need to wait for keeper execution
• TWAP orders are executed as multiple transactions

• Scripts:

  scripts/

  • trade-assistant.js

    - trading assistant (natural language orders)

  • trade-cli.js

    - CLI tool

  • open-position.js

    - open position script

  • close-position.js

    - close position script

  • add-liquidity.js

    - add liquidity

  • remove-liquidity.js

    - remove liquidity

  • query.js

    - query tool

  • update-markets.js

    - update market list
• Reference docs:

  references/

  • liquidity-deposit-withdrawal.md - add/remove liquidity details
  • setup.md - environment and dependencies
  • createOrder-updateOrder-cancleOrder.md - order contract reference
• Config:

  assets/

  • addresses.json

    - contract addresses (ExchangeRouter, DepositVault, WithdrawalVault, WNT)

  • markets.json

    - market config

  • celo-tokens.json

    - token decimals

  • celo.env.local

    - environment variables (RPC, private key)

  • abis/

    - contract ABIs

  • orders/

    - order and liquidity config directory

• Market pair: BTC, ETH, CELO, EURm, JPYm, NGNm, AUDm, GBPm
• Order type: market / limit
• Direction: long / short (open long/open short/long/short)
• Margin: any amount (denominated in USDT/USD/U)
• Leverage: default 1x, can be specified (e.g. 2x, 5x, 10x)
• Trigger price: required for limit and stop orders

1. User inputs a natural-language instruction
2. Assistant parses and validates parameters
3. Automatically generates an order config file
4. Prints the execution command
5. User copies and runs the command to execute the trade

• UI reference: https://www.updown.xyz/#/trade