Skip to content

Latest commit

 

History

History
215 lines (168 loc) · 13 KB

README.md

File metadata and controls

215 lines (168 loc) · 13 KB
description
API examples

API Endpoints

This API is a simple wrapper around the SDK offered for convenience on getting estimated bonder fee and transfer status.

Although this API is offered as a free service, it's recommended to host your own API server (see docs here) to not have any rate limit restrictions.

Endpoints

GET /v1/quote

Get estimated bonder fee to use for transfers

Input query parameters:

Parameters Description
amount (required) Amount in smallest use (eg. amount=1000000 which is 1 USDC)
token (required) Token symbol (eg. token=USDC)
fromChain (required) From chain slug (eg. fromChain=optimism)
toChain (required) To chain slug (eg. toChain=polygon)
slippage (required) Slippage percentage (eg. slippage=0.5 which is 0.5%)
network (optional) Ethereum network to use. Options are mainnet (default), goerli for testnet (eg. network=goerli)

Chain options are: ethereum, optimism, arbitrum, polygon, gnosis, nova, base

Example request

curl "https://api.hop.exchange/v1/quote?amount=1000000&token=USDC&fromChain=optimism&toChain=arbitrum&slippage=0.5"

Example response

{
  "amountIn": "1000000",
  "slippage": 0.5,
  "amountOutMin": "743633",
  "destinationAmountOutMin": "742915",
  "bonderFee": "250515",
  "estimatedRecieved": "747908",
  "deadline": 1679862208,
  "destinationDeadline": 1679862208
}

Output response:

Parameters Description
amountIn Specified amount in.
slippage Specified slippage.
amountOutMin The minimum amount out to receive from AMM at origin chain (or destination chain if sending from L1), taking account AMM fees, slippage, and total bonder fee.
destinationAmountOutMin The minimum amount out to receive from AMM at destination chain, taking account, AMM fees, slippage, and total bonder fee. Note: There is no AMM on L1, so this should be 0 when sending to L1.
bonderFee The suggested bonder fee for the amount in. The bonder fee also includes the cost of the destination transaction fee.
estimatedReceived The estimated amount you'll receive at the destination taking account all fees and slippage.
deadline A default deadline of 7 days to perform swap at origin AMM (or destination AMM if sending from L1).
destinationDeadline A default deadline of 7 days to perform swap at destination AMM. Note: There is no AMM on L1, so this should be 0 when sending to L1.

GET /v1/transfer-status

Get transfer status for tx

Input query parameters:

Parameters Description
transferHash (optional*) Origin transfer transaction hash
transferId (optional*) Transfer ID
network (optional) Ethereum network to use. Options are mainnet (default), goerli for testnet

* Must use at lease one option, either transactionHash or transferId.

Example request

curl "https://api.hop.exchange/v1/transfer-status?transactionHash=0xbe6953dac8149e3f4d3a5719445170fb9835c461a980cbdaf9ad5cce10c9d27c"

Example response

{
  "transferId": "0x5a15b2abd4d0f2e5d0ea3d5fc93758374b14940096487d70f7c95b5393fc9c89",
  "transactionHash": "0xbe6953dac8149e3f4d3a5719445170fb9835c461a980cbdaf9ad5cce10c9d27c",
  "sourceChainId": 10,
  "sourceChainSlug": "optimism",
  "destinationChainId": 42161,
  "destinationChainSlug": "arbitrum",
  "accountAddress": "0xd813a52b1158fc08f69ba52ca72ca4360e255ba3",
  "amount": "2996498",
  "amountFormatted": 2.996498,
  "amountUsd": 3.004011668430896,
  "amountOutMin": "2503144",
  "deadline": 1662159408,
  "recipientAddress": "0xd813a52b1158fc08f69ba52ca72ca4360e255ba3",
  "bonderFee": "479123",
  "bonderFeeFormatted": 0.479123,
  "bonderFeeUsd": 0.4803243928791597,
  "bonded": true,
  "bondTransactionHash": "0x659225113a0711d73bd576d2edb916b1031d4fb3e422a08ee8e0f863c4fb5af7",
  "bonderAddress": "0xa6a688f107851131f0e1dce493ebbebfaf99203e",
  "token": "USDC",
  "timestamp": 1661554612
}

Output response:

Parameters Description
transferId Transfer ID
transactionHash Origin transaction hash
sourceChainId Chain ID of origin chain
sourceChainSlug Chain slug of origin chain
destinationChainId Chain ID of destination chain
destinationChainSlug Chain slug of destination chain
accountAddress Address of transfer originator
amount Original amount transferred in smallest unit (eg. wei)
amountFormatted Original amount transferred in human readable format
amountUsd Original amount transferred in USD
amountOutMin The minimum amount out specified for AMM swap
deadline Deadline timestamp specified in transfer
recipientAddress Address of recipient set for transfer
bonderFee The bonder fee amount specified in transfer in smallest unit in terms of token transferred (eg. wei)
bonderFeeFormatted The bonder fee amount specified in transfer in human readable format
bonded True if this transfer has been bonded (received) at the destination. Will be false if the transfer is still pending or is unbondable
bondTransactionHash Bond (received) destination transaction hash
bonderAddress Address of bonder for this transfer
token Token symbol of asset bridged
timestamp Unix timestamp of origin transfer transaction

GET /v1/available-routes

Get available routes

Input query parameters:

Parameters Description
network (optional) Ethereum network to use. Options are mainnet (default), goerli for testnet

Example request

curl "https://api.hop.exchange/v1/available-routes"

Example response

[
  {
    "token": "USDC",
    "sourceChain": "ethereum",
    "sourceChainId": 1,
    "destinationChain": "optimism",
    "destinationChainId": 100
  },
  {
    "token": "ETH",
    "sourceChain": "base",
    "sourceChainId": 8453,
    "destinationChain": "arbitrum",
    "destinationChainId": 42161
  },
  ...
]

Output response:

Parameters Description
token Token Symbol
sourceChainSlug Source chain slug
sourceChainId Source chain ID
destinationChainSlug Destination chain slug
destinationChainId Destination chain ID

Using custom RPC providers

You can set query parameter to specify what RPC url to use for a chain.

By default, public RPC urls are used, which are subject to rate limits. You can get better performance by specifying your own custom provider instead.

Input query parameters:

Parameters Description
rpcUrl[ethereum] (optional) Ethereum RPC url (eg. rpcUrl[ethereum]=https://mainnet.infura.io/v3/84842078b09946638c03157f83405213)
rpcUrl[optimism] (optional) Optimism RPC url (eg. rpcUrl[optimism]=https://mainnet.optimism.io)
rpcUrl[arbitrum] (optional) Arbitrum RPC url (eg. rpcUrl[arbitrum]=https://arb1.arbitrum.io/rpc)
rpcUrl[polygon] (optional) Polygon RPC url (eg. rpcUrl[polygon]=https://polygon-rpc.com)
rpcUrl[gnosis] (optional) Gnosis Chain RPC url (eg. rpcUrl[gnosis]=https://rpc.gnosischain.com)
rpcUrl[nova] (optional) Nova RPC url (eg. rpcUrl[nova]=https://nova.arbitrum.io/rpc)
rpcUrl[base] (optional) Base RPC url (eg. rpcUrl[base]=https://goerli.base.org)

Example request

curl -g "https://api.hop.exchange/v1/quote?amount=1000000&token=USDC&fromChain=polygon&toChain=optimism&slippage=0.5&rpcUrl[polygon]=https://polygon-rpc.com&rpcUrl[gnosis]=https://mainnet.optimism.io"

Source code

The API server source code is available on github.

Additional endpoints

If you're looking for a complete API to compose bridge transfer transactions, checking approvals, and more; check out this self hosted server example on github.