GET /firm-quote

Obtaining Signed Order data for selling an ERC20 or Native Token and submitting to Native Router for swap execution.

GET https://newapi.native.org/v1/firm-quote

This endpoint provides transaction data based on the requested token and token amount. For examples of using this endpoint, please refer to this section.

For native token swaps, Native uses 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE to represent the token address of the native token.

Headers

Name	Description
apiKey	API Key retrieved from the Native app

Params

Name	Description
src_chain*	The blockchain name belonging to the token_in address - Refer to the GET /chains API here for more information.
dst_chain*	The blockchain name belonging to the token_out address - Refer to the GET /chains API here for more information.
token_in*	Address of the token to be sold
token_out*	Address of the token to be bought
amount	Amount of token to be sold, in ether unit
amount_wei	Amount of token to be sold, in wei unit
from_address*	Address of the user that sells the token_in
beneficiary_address	Address of the end user that initiated the swap request
to_address	Address of the user that receives the token_out If empty, this address will be the same as from_address
expiry_time	Expiry time in seconds This variable will be passed on to the market makers to consider when they give the quote. Market makers would be able to give better quote for a shorter expiry time. It will affect the deadlineTimestamp in the response if the quote from that market maker is chosen. If not provided, we will just use the default expiry time by the liquidity source.
slippage	Number in percentage value For example, passing the value 5 means 5%, 0.1 means 0.1% slippage tolerance. By default it's 0.

Example

https://newapi.native.org/v1/firm-quote?chain=ethereum&token_in=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&token_out=0xdAC17F958D2ee523a2206206994597C13D831ec7&amount=1&from_address=0x42d4e9ee3f725c84b7934e4fda64f2be0f803130&deadline_timestamp=1692085583

In this example, wallet 0x42d4e9ee3f725c84b7934e4fda64f2be0f803130 requests transaction data for swapping 1 ETH to USDT on the Ethereum network.

Response

Name	Description
success	Indicates if the signing of the firm quote was successful
orders	Array of order objects. Refer to Params for more details.
widgetFee	Contains the widgetFee details. feeRecipient is the address that will receive the widget fee and feeRate is the amount of fees that the fee recipient will receive.
widgetFeeSignature	The signature of the transaction request and the widget fee
recipient	The address of the seller/swapper
calldata	The byte encoding for the orders object
amountIn	The amount of sellerToken in wei, that will be sold to the buyer
amountOut	The amount of buyerToken in wei, that the buyer will be receiving
toWrap	Indicates if the order needs to be wrapped
toUnwrap	Indicates if the order needs to be unwrapped
fallbackSwapDataArray	This is the raw input data that will be executed by Native fallback
source	Indicates the liquidity provider that is providing this firm-quote
txRequest	The transaction request to be executed by the NativeRouter. The calldata contains the raw input data that will be executed by the NativeRouter. The target here is the address of the NativeRouter.

Example

{
    "success": true,
    "orders": [
        {
            "id": 96399673,
            "signer": "0x2008b6c3D07B061A84F790C035c2f6dC11A0be70",
            "buyer": "0x3D130BF4686B3D4b6eB91a8E26Ac629c5BEA6082",
            "seller": "0x42d4e9ee3f725c84b7934e4fda64f2be0f803130",
            "buyerToken": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
            "sellerToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "buyerTokenAmount": "1864151208",
            "sellerTokenAmount": "1000000000000000000",
            "caller": "0x42d4e9ee3f725c84b7934e4fda64f2be0f803130",
            "quoteId": "83d5a121-4499-4117-9066-1c33af753959",
            "deadlineTimestamp": 1698307683
        }
    ],
    "widgetFee": {
        "signer": "0x67297ee4eb097e072b4ab6f1620268061ae80464",
        "feeRecipient": "0x2397D2fdE31C5704b02AC1ec9B770f23D70d8EC4",
        "feeRate": 0
    },
    "widgetFeeSignature": "0x4c63b2af7d2b13dcbc92c3ba5d37fbb7e959c6d455331df3f23a881b1605a5f45336561438d5386631d9c21b07fb4a9cf45ae7ea28c956284d804e3dc3ce9ffd1b",
    "recipient": "0x42d4e9ee3f725c84b7934e4fda64f2be0f803130",
    "calldata": "0x00000000000000000000000000000000000000000000000000167edf2d4214292008b6c3d07b061a84f790c035c2f6dc11a0be703d130bf4686b3d4b6eb91a8e26ac629c5bea608242d4e9ee3f725c84b7934e4fda64f2be0f803130dac17f958d2ee523a2206206994597c13d831ec7c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000000000000000000000000000000000006f1cb0a80000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000653a1e6342d4e9ee3f725c84b7934e4fda64f2be0f80313083d5a1214499411790661c33af7539597f7f43ca3401a963e6e90ea14dbc9af105aa82ed95f6c5efc75115f51c94fc0e374f2889904b528cacca114cf57a90aaf925520be22cfd36189b9d4c34baa4721c",
    "amountIn": "1000000000000000000",
    "amountOut": "1864151208",
    "toWrap": false,
    "toUnwrap": false,
    "fallbackSwapDataArray": [],
    "source": "p1",
    "txRequest": {
        "target": "0xEAd050515E10fDB3540ccD6f8236C46790508A76",
        "calldata": "0xc7cd97480000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000012000000000000000000000000042d4e9ee3f725c84b7934e4fda64f2be0f8031300000000000000000000000000000000000000000000000000de0b6b3a7640000000000000000000000000000000000000000000000000000000000006e003e3f00000000000000000000000067297ee4eb097e072b4ab6f1620268061ae804640000000000000000000000002397d2fde31c5704b02ac1ec9b770f23d70d8ec4000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000014900000000000000000000000000000000000000000000000000167edf2d4214292008b6c3d07b061a84f790c035c2f6dc11a0be703d130bf4686b3d4b6eb91a8e26ac629c5bea608242d4e9ee3f725c84b7934e4fda64f2be0f803130dac17f958d2ee523a2206206994597c13d831ec7c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000000000000000000000000000000000006f1cb0a80000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000653a1e6342d4e9ee3f725c84b7934e4fda64f2be0f80313083d5a1214499411790661c33af7539597f7f43ca3401a963e6e90ea14dbc9af105aa82ed95f6c5efc75115f51c94fc0e374f2889904b528cacca114cf57a90aaf925520be22cfd36189b9d4c34baa4721c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000414c63b2af7d2b13dcbc92c3ba5d37fbb7e959c6d455331df3f23a881b1605a5f45336561438d5386631d9c21b07fb4a9cf45ae7ea28c956284d804e3dc3ce9ffd1b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "value": "1000000000000000000"
    }
}

In the response above, Native returns 1,864.151208 USDT for the order submitted.

Note: To send the transaction on-chain, you can utilize the txRequest response. This response will be identical to the one provided by the GET /calldata API endpoint.

Explore this endpoint and see how it works here.