Selected API Endpoints for Integrations

Full documentation with API explorer is available at Mach API Explorer.

Ingesting Mach Config

Get Configuration

/get_config

Method: GETReturns a JSON object that defines the chains and tokens that Mach supports. All chain IDs, token contracts, swap contracts and necessary information for routing transactions to Mach can be retrieved from this endpoint.

This endpoint is essential for any integration as it provides all the necessary contract addresses, token details, and chain information required to interact with the Mach protocol.

Response Format

{
  "chains": [
    {
      "id": "arbitrum",
      "chainId": 42161,
      "name": "Arbitrum One",
      "nativeToken": "ETH",
      "swapContract": "0x...",
      "rpcUrl": "https://arb1.arbitrum.io/rpc"
    },
    // Other supported chains
  ],
  "tokens": [
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "addresses": {
        "arbitrum": "0x...",
        "optimism": "0x...",
        // Other chains
      }
    },
    // Other supported tokens
  ]
}

Gas Estimation

Get Gas Estimate

/v1/orders/gas

Method: GETEstimates the gas price on the given chain.

Query Parameters

Parameter	Type	Description
chain	string	Chain identifier (e.g., “avalanche”, “ethereum”)

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/orders/gas?chain=avalanche

Example Response

{
  "gas_estimate": 21000,
  "gas_price": 25000000000
}

Quote Endpoints

Request Quote

/v1/quotes

Method: POSTReturns a price quote for a cross-chain swap based on the provided parameters.

Request Parameters

Parameter	Type	Description
wallet_address	string	User’s wallet address (optional, defaults to zero address)
target_address	string	Optional recipient address if different from wallet
src_chain	string	Source chain identifier (e.g., “arbitrum”, “optimism”)
dst_chain	string	Destination chain identifier
src_asset_address	string	Source token contract address
dst_asset_address	string	Destination token contract address
src_amount	integer	Amount to swap in the smallest unit of the source token

Example Request

POST https://mach-prod-536329393577.asia-northeast1.run.app/v1/quotes
Content-Type: application/json

{
  "wallet_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "src_chain": "avalanche",
  "dst_chain": "arbitrum",
  "src_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "dst_asset_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
  "src_amount": 1000000
}

Response Format

{
  "wallet_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "src_chain": "avalanche",
  "dst_chain": "arbitrum",
  "src_amount": "1000000",
  "dst_amount": "997000",
  "bond_amount": "1500000",
  "bond_fee": 3000,
  "src_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "dst_asset_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
  "bond_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "challenge_offset": 900,
  "challenge_window": 300,
  "invalid_amount": false,
  "liquidity_source": "market_maker",
  "created_at": "2023-05-01T12:34:56Z",
  "expires_at": "2023-05-01T12:39:56Z",
  "order_data": {
    "contract_address": "0x123...",
    "order_direction": {
      "src_token_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      "dst_token_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
      "src_lzc": 30106,
      "dst_lzc": 30110
    },
    "order_funding": {
      "src_amount_in": "1000000",
      "dst_amount_out": "997000",
      "bond_token_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      "bond_amount": "1500000",
      "bond_fee": "3000"
    },
    "order_expiration": {
      "timestamp": 1682944796,
      "challenge_offset": 900,
      "challenge_window": 300
    },
    "target_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
    "filler_address": "0x456..."
  },
  "destination_transaction_fee": 500000,
  "destination_transaction_fee_usd": 0.50,
  "destination_transaction_fee_after_subsidy": 100000,
  "destination_transaction_fee_after_subsidy_usd": 0.10,
  "destination_transaction_fee_subsidy_usd": 0.40,
  "reject_order": false
}

Order Endpoints

Submit Order

/v1/orders

Method: POSTAfter receiving a confirmed transaction calling the PlaceTrade function on our Optimistic Swap smart contract, you can send the transaction data to our service to fulfill the order for the user.

Request Parameters

Parameter	Type	Description
chain	string	The chain where the transaction was submitted
place_taker_tx	string	The transaction hash of the PlaceTrade call
referral_code	string	Optional referral code

Example Request

POST https://mach-prod-536329393577.asia-northeast1.run.app/v1/orders
Content-Type: application/json

{
  "chain": "optimism",
  "place_taker_tx": "0x50da55b159ccd423ebcb315dd2949202e584473960008274514c5088f3d26de7",
  "referral_code": "ABC"
}

Example Response

{
  "id": "6368f169-d9ad-53ec-b797-81b4dc74c257",
  "taker_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "maker_address": "0x123456789abcdef123456789abcdef123456789a",
  "src_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "dst_asset_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
  "src_chain": "avalanche",
  "dst_chain": "arbitrum",
  "src_amount": 1000000,
  "dst_amount": 997000,
  "created_at": "2023-05-01T12:34:56Z",
  "filled_at": "2023-05-01T12:35:30Z",
  "expires_at": "2023-05-01T12:39:56Z",
  "completed": true,
  "place_tx": "0x50da55b159ccd423ebcb315dd2949202e584473960008274514c5088f3d26de7",
  "fill_tx": "0x60ea66b269ccd423ebcb315dd2949202e584473960008274514c5088f3d26ff8",
  "eta": 0,
  "order_type": "default"
}

Get User Orders

/v1/orders

Method: GETRetrieve orders that were submitted by a wallet.

Query Parameters

Parameter	Type	Description
wallet	string	The wallet address to retrieve orders for

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/orders?wallet=0xb20094DFede30AbEe3a8d549BbA828b6fd771106

Example Response

[
  {
    "id": "6368f169-d9ad-53ec-b797-81b4dc74c257",
    "taker_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
    "maker_address": "0x123456789abcdef123456789abcdef123456789a",
    "src_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
    "dst_asset_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
    "src_chain": "avalanche",
    "dst_chain": "arbitrum",
    "src_amount": 1000000,
    "dst_amount": 997000,
    "created_at": "2023-05-01T12:34:56Z",
    "filled_at": "2023-05-01T12:35:30Z",
    "expires_at": "2023-05-01T12:39:56Z",
    "completed": true,
    "place_tx": "0x50da55b159ccd423ebcb315dd2949202e584473960008274514c5088f3d26de7",
    "fill_tx": "0x60ea66b269ccd423ebcb315dd2949202e584473960008274514c5088f3d26ff8",
    "eta": 0,
    "order_type": "default"
  },
  // Additional orders...
]

Get Order Status

/v1/orders/{order_id}

Method: GETRetrieve the current status of an order.

Path Parameters

Parameter	Type	Description
order_id	string	The ID of the order to retrieve

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/orders/6368f169-d9ad-53ec-b797-81b4dc74c257

Example Response

{
  "id": "6368f169-d9ad-53ec-b797-81b4dc74c257",
  "taker_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "maker_address": "0x123456789abcdef123456789abcdef123456789a",
  "src_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "dst_asset_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
  "src_chain": "avalanche",
  "dst_chain": "arbitrum",
  "src_amount": 1000000,
  "dst_amount": 997000,
  "created_at": "2023-05-01T12:34:56Z",
  "filled_at": "2023-05-01T12:35:30Z",
  "expires_at": "2023-05-01T12:39:56Z",
  "completed": true,
  "place_tx": "0x50da55b159ccd423ebcb315dd2949202e584473960008274514c5088f3d26de7",
  "fill_tx": "0x60ea66b269ccd423ebcb315dd2949202e584473960008274514c5088f3d26ff8",
  "eta": 0,
  "order_type": "default"
}

CCTP Endpoints

/v1/orders/cctp

Method: POSTSubmit a Circle Cross-Chain Transfer Protocol (CCTP) transaction.

Request Parameters

Parameter	Type	Description
chain	string	Source chain of the CCTP transaction
burn_tx	string	Transaction hash of the CCTP burn transaction
solana_token_owner_address	string	(Optional) Solana token owner address, if applicable

Example Request

POST https://mach-prod-536329393577.asia-northeast1.run.app/v1/orders/cctp
Content-Type: application/json

{
  "chain": "avalanche",
  "burn_tx": "0x3cdc8d4da0e74b08f453f311e2031b2d518c769cc8d9b5783043a2e35a9e6428",
  "solana_token_owner_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}

Example Response

{
  "id": "6368f169-d9ad-53ec-b797-81b4dc74c257",
  "taker_address": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "maker_address": null,
  "src_asset_address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "dst_asset_address": "0x498Bf2B1e120FeD3ad3D42EA2165E9b73f99C1e5",
  "src_chain": "avalanche",
  "dst_chain": "arbitrum",
  "src_amount": 1000000,
  "dst_amount": 997000,
  "created_at": "2023-05-01T12:34:56Z",
  "filled_at": null,
  "expires_at": null,
  "completed": false,
  "place_tx": "0x3cdc8d4da0e74b08f453f311e2031b2d518c769cc8d9b5783043a2e35a9e6428",
  "fill_tx": null,
  "eta": 300,
  "order_type": "cctp"
}

Token Endpoints

/v1/tokens/token_info

Method: GETFetches token information based on the provided blockchain chain and token address.

Query Parameters

Parameter	Type	Description
chain	string	Blockchain chain identifier
token_address	string	Ethereum token contract address

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/tokens/token_info?chain=arbitrum&token_address=0xff970a61a04b1ca14834a43f5de4533ebddb5cc8

Example Response

{
  "chain": "arbitrum",
  "symbol": "USDC",
  "address": "0xff970a61a04b1ca14834a43f5de4533ebddb5cc8",
  "decimals": 6,
  "usd_est": 1,
  "is_wrapped": false,
  "cex_tickers": {
    "binance": "USDC"
  },
  "name": "USD Coin"
}

/v1/tokens/get_all_tokens_from_db

Method: GETFetches all tokens. If a chain is provided, it fetches tokens for that specific chain.

Query Parameters

Parameter	Type	Description
chain	string	(Optional) Blockchain chain identifier

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/tokens/get_all_tokens_from_db?chain=arbitrum

Example Response

[
  {
    "chain": "arbitrum",
    "symbol": "USDC",
    "address": "0xff970a61a04b1ca14834a43f5de4533ebddb5cc8",
    "decimals": 6,
    "usd_est": 1,
    "is_wrapped": false,
    "cex_tickers": {
      "binance": "USDC"
    },
    "name": "USD Coin"
  },
  {
    "chain": "arbitrum",
    "symbol": "WETH",
    "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
    "decimals": 18,
    "usd_est": 3500,
    "is_wrapped": true,
    "cex_tickers": {
      "binance": "ETH"
    },
    "name": "Wrapped Ether"
  }
  // Additional tokens...
]

Points Endpoints

/v1/points

Method: GETReturns the top wallets by points.

Query Parameters

Parameter	Type	Description
limit	integer	(Optional) Number of top wallets to return (default: 10, max: 100)

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/points?limit=10

Example Response

[
  {
    "wallet": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
    "points": 1500
  },
  {
    "wallet": "0xa10094DFede30AbEe3a8d549BbA828b6fd771107",
    "points": 1200
  }
  // Additional wallets...
]

/v1/points/{wallet}

Method: GETReturns points for a specific wallet address.

Path Parameters

Parameter	Type	Description
wallet	string	The wallet address to retrieve points for

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/points/0xb20094DFede30AbEe3a8d549BbA828b6fd771106

Example Response

{
  "wallet": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "points": 1500
}

/v1/points/referral_code/{referral_code}

Method: POSTGets information about a referral code.

Path Parameters

Parameter	Type	Description
referral_code	string	The referral code to look up

Example Request

POST https://mach-prod-536329393577.asia-northeast1.run.app/v1/points/referral_code/ABC

Example Response

{
  "code": "ABC",
  "percentage": 10,
  "referrer": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106"
}

Twitter Integration Endpoints

/v1/twitter/recent_tweet_id

Method: GETReturns the ID of the most recent tweet for Twitter engagement tasks.

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/v1/twitter/recent_tweet_id

Example Response

{
  "tweet": "1512345678901234567"
}

/v1/twitter/verify_retweet

Method: POSTVerifies if a user has retweeted a specific tweet.

Request Parameters

Parameter	Type	Description
wallet	string	The wallet address of the user
username	string	The Twitter username
tweet_id	string	The ID of the tweet to verify

Example Request

POST https://mach-prod-536329393577.asia-northeast1.run.app/v1/twitter/verify_retweet
Content-Type: application/json

{
  "wallet": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "username": "user123",
  "tweet_id": "1512345678901234567"
}

Example Response

{
  "verified": true
}

/v1/twitter/submit_user_data

Method: POSTSubmits user data for Twitter integration.

Request Parameters

Parameter	Type	Description
wallet	string	The wallet address of the user
twitter_handle	string	The Twitter handle
telegram_handle	string	(Optional) The Telegram handle
email	string	(Optional) The user’s email

Example Request

POST https://mach-prod-536329393577.asia-northeast1.run.app/v1/twitter/submit_user_data
Content-Type: application/json

{
  "wallet": "0xb20094DFede30AbEe3a8d549BbA828b6fd771106",
  "twitter_handle": "user123",
  "telegram_handle": "user123",
  "email": "[email protected]"
}

Example Response

{
  "verified": true
}

Utility Endpoints

/tokenBalances

Method: GETReturns token balances for a wallet address.

Query Parameters

Parameter	Type	Description
wallet_address	string	Wallet address (supports Ethereum and Solana addresses)

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/tokenBalances?wallet_address=0x886431aee6486D68863D2963F3E7BC8683990210

/gas_token_prices

Method: GETReturns current gas token prices.

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/gas_token_prices

/ping

Method: GETSimple ping endpoint to check if the API is up.

Example Request

GET https://mach-prod-536329393577.asia-northeast1.run.app/ping

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Common status codes include:

Status Code	Description
200	OK - The request succeeded
400	Bad Request - The request could not be processed due to client error
404	Not Found - The requested resource was not found
422	Unprocessable Entity - The request was well-formed but could not be processed
500	Internal Server Error - Something went wrong on the server

When handling errors, always provide clear feedback to users about what went wrong and what they can do to resolve the issue.

​Selected API Endpoints for Integrations

​Ingesting Mach Config

​Get Configuration

/get_config

​Response Format

​Gas Estimation

​Get Gas Estimate

/v1/orders/gas

​Query Parameters

​Example Request

​Example Response

​Quote Endpoints

​Request Quote

/v1/quotes

​Request Parameters

​Example Request

​Response Format

​Order Endpoints

​Submit Order

/v1/orders

​Request Parameters

​Example Request

​Example Response

​Get User Orders

/v1/orders

​Query Parameters

​Example Request

​Example Response

​Get Order Status

/v1/orders/{order_id}

​Path Parameters

​Example Request

​Example Response

​CCTP Endpoints

/v1/orders/cctp

​Request Parameters

​Example Request

​Example Response

​Token Endpoints

/v1/tokens/token_info

​Query Parameters

​Example Request

​Example Response

/v1/tokens/get_all_tokens_from_db

​Query Parameters

​Example Request

​Example Response

​Points Endpoints

/v1/points

​Query Parameters

​Example Request

​Example Response

/v1/points/{wallet}

​Path Parameters

​Example Request

​Example Response

/v1/points/referral_code/{referral_code}

​Path Parameters

​Example Request

​Example Response

​Twitter Integration Endpoints

/v1/twitter/recent_tweet_id

​Example Request

​Example Response

/v1/twitter/verify_retweet

​Request Parameters

​Example Request

​Example Response

/v1/twitter/submit_user_data

​Request Parameters

​Example Request

​Example Response

​Utility Endpoints

/tokenBalances

​Query Parameters

​Example Request

/gas_token_prices

​Example Request

/ping

​Example Request

Selected API Endpoints for Integrations

Ingesting Mach Config

Get Configuration

Response Format

Gas Estimation

Get Gas Estimate

Query Parameters

Example Request

Example Response

Quote Endpoints

Request Quote

Request Parameters

Example Request

Response Format

Order Endpoints

Submit Order

Request Parameters

Example Request

Example Response

Get User Orders

Query Parameters

Example Request

Example Response

Get Order Status

Path Parameters

Example Request

Example Response

CCTP Endpoints

Request Parameters

Example Request

Example Response

Token Endpoints

Query Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Points Endpoints

Query Parameters

Example Request

Example Response

Path Parameters

Example Request

Example Response

Path Parameters

Example Request

Example Response

Twitter Integration Endpoints

Example Request

Example Response

Request Parameters

Example Request

Example Response

Request Parameters

Example Request

Example Response

Utility Endpoints

Query Parameters

Example Request

Example Request

Example Request

Error Handling