Bridge API

The GX Exchange Bridge enables deposits from external chains and withdrawals back to them. This page documents the API endpoints for bridge operations.

Overview

The bridge supports moving USDC between GX Exchange and supported external chains. Deposits are initiated on the source chain and confirmed on GX Chain. Withdrawals are initiated via the GX Exchange API and settled on the destination chain.

Supported Chains

Chain	Chain ID	Asset	Status
Ethereum	1	USDC	Active
Arbitrum	42161	USDC	Active
Base	8453	USDC	Active
Optimism	10	USDC	Active

Deposits

Deposits are initiated by sending USDC to the GX Bridge contract on the source chain.

Deposit Flow

Approve the bridge contract to spend your USDC on the source chain
Call the deposit() function on the bridge contract with the amount and your GX address
Wait for the source chain transaction to be confirmed
The bridge relayer detects the deposit and credits your GX Exchange account
Funds appear in your trading balance (typically within 1-5 minutes depending on source chain finality)

Checking Deposit Status

Query your clearinghouse state to verify the deposit was credited:

POST /info
{ "type": "clearinghouseState", "user": "0xYourAddress..." }

The withdrawable field reflects your available balance including recent deposits.

Withdrawals

Withdrawals are initiated through the POST /exchange endpoint using the withdraw action type.

Withdraw Action

{
  "action": {
    "type": "withdraw",
    "destination": "0xRecipientAddress...",
    "amount": "500.0"
  },
  "nonce": 1700000000123,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Field	Type	Description
`destination`	`address`	Recipient address on the destination chain
`amount`	`string`	USDC amount to withdraw

Withdrawal Constraints

Constraint	Value
Minimum withdrawal	10 USDC
Maximum withdrawal	No hard limit (subject to available liquidity)
Bridge fee	~1 USDC (deducted from withdrawal amount)
Processing time	5 — 30 minutes depending on destination chain

Response

{
  "status": "ok",
  "response": {
    "type": "withdraw",
    "data": {
      "withdrawalId": "wd_abc123...",
      "amount": "499.0",
      "fee": "1.0",
      "destination": "0xRecipientAddress...",
      "status": "pending"
    }
  }
}

Internal USD Transfers

Transfer USDC between GX Exchange addresses without going through the bridge:

{
  "action": {
    "type": "usdTransfer",
    "destination": "0xRecipientAddress...",
    "amount": "1000.0"
  },
  "nonce": 1700000000123,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Internal transfers are instant and free — no bridge fee is charged.

Code Examples

TypeScript — Withdraw

import { GxClient } from "@gx-exchange/sdk";
 
const client = new GxClient();
await client.connect("https://api.gx.exchange");
client.setWallet("0xYourPrivateKey...");
 
const result = await client.withdraw({
  destination: "0xRecipientAddress...",
  amount: "500.0",
});
 
console.log("Withdrawal ID:", result.response.data.withdrawalId);
console.log("Net amount:", result.response.data.amount);
console.log("Fee:", result.response.data.fee);

Python — Withdraw

from gx_exchange.exchange import Exchange
from gx_exchange.utils.constants import MAINNET_API_URL
import eth_account
 
account = eth_account.Account.from_key("0xYourPrivateKey...")
exchange = Exchange(account, MAINNET_API_URL)
 
result = exchange.withdraw(
    destination="0xRecipientAddress...",
    amount="500.0",
)
print(f"Withdrawal: {result}")

TypeScript — Internal Transfer

const transfer = await client.usdTransfer({
  destination: "0xRecipientAddress...",
  amount: "1000.0",
});
 
console.log("Transfer status:", transfer.status);

Error Responses

Error	Cause	Resolution
`Insufficient balance`	Withdrawal amount exceeds available balance	Reduce amount or wait for pending orders to settle
`Amount below minimum`	Withdrawal below 10 USDC minimum	Increase withdrawal amount
`Invalid destination`	Destination address is malformed	Verify the address format
`Bridge temporarily unavailable`	Bridge relayer maintenance	Retry after a few minutes

Optimizing Latency Deploying GIP-1 & GIP-2 Assets