GET /firm-quote

Get signed order data for selling a ERC20 / native token. Submit the return data to Native router to execute swap.

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

This endpoint provides transaction data given the requested token and token amount. Please refer to execute swap section for examples of using the endpoint.

Native supports native token swap by using 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. You can refer to supported chain API.
dst_chain*	The blockchain name belonging to the token_out address. You can refer to supported chain API.
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 percent. 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 for transaction data for swapping 1 ETH to USDT on Ethereum.

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 response:

{
    "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 sent in the example.

Note that to send the transaction on chain, you can utilize the txRequest response. This response will be exactly the same as GET /calldata API endpoint.

You may try this endpoint out here.