Trade Tokens

Get A Quote

If a token is already migrated, you can still get a quote using the following method. However, we will always use the pool that the token has migrated to, this may not be the best quote.

To get a quote , we call the quoteExactInput function:

/// @notice Parameters for quoting the output amount for a given input
struct QuoteExactInputParams {
    /// @notice The address of the input token (use address(0) for native asset)
    address inputToken;
    /// @notice The address of the output token (use address(0) for native asset)
    address outputToken;
    /// @notice The amount of input token to swap (in input token decimals)
    uint256 inputAmount;
}

/// @notice Quote the output amount for a given input
/// @param params The quote parameters
/// @return outputAmount The quoted output amount
/// @dev refer to the swapExactInput method for the scenarios
function quoteExactInput(QuoteExactInputParams calldata params) external returns (uint256 outputAmount);

Note: the quoteExactInput method is not a view function, but we don’t need to send a transaction to get the quote (an eth_call or the simulation in viem will do the work) .

Here are the possible scenarios:

• When the quote token is the native gas token (BNB or ETH):

  • buy a token:

    • inputToken is zero address, representing the gas token

    • outputToken is the token you wanna buy

  • sell a token:

    • inputToken is the token you wanna sell

    • outputToken is zero address, representing the gas token

• When the quote token is not the native gas token (taking USD1 as an example) :

  • buy a token with USD1:

    • inputToken is USD1 address

    • outputToken is the token you wanna buy

  • buy with native gas token (only when the token’s nativeToQuoteSwap is enabled , check below to inspect if a token’s quote token supports nativeToQuoteSwap ):

    • inputToken is zero address, representing the gas token

    • outputToken is the token you wanna buy

    • under the hood, we will help you swap BNB for for USD1 on PancakeSwap as an intermediate step in the contract.

  • sell a token:

    • inputToken is the token you wanna sell

    • outputToken is USD1

  • Sell directly from token to BNB is also supported, but we will not support this in our UI.

Swap

To swap we call the swapExactInput method:

/// @notice Parameters for swapping exact input amount for output token
struct ExactInputParams {
    /// @notice The address of the input token (use address(0) for native asset)
    address inputToken;
    /// @notice The address of the output token (use address(0) for native asset)
    address outputToken;
    /// @notice The amount of input token to swap (in input token decimals)
    uint256 inputAmount;
    /// @notice The minimum amount of output token to receive
    uint256 minOutputAmount;
    /// @notice Optional permit data for the input token (can be empty)
    bytes permitData;
}

/// @notice Swap exact input amount for output token
/// @param params The swap parameters
/// @return outputAmount The amount of output token received
/// @dev Here are some possible scenarios:
///   If the token's reserve is BNB or ETH (i.e: the quote token is the native gas token):
///      - BUY: input token is address(0), output token is the token address
///      - SELL: input token is the token address, output token is address(0)
///   If the token's reserve is another ERC20 token (eg. USD*, i.e, the quote token is an ERC20 token):
///      - BUY with USD*: input token is the USD* address, output token is the token address
///      - SELL for USD*: input token is the token address, output token is the USD* address
///      - BUY with BNB or ETH: input token is address(0), output token is the token address.
///        (Note: this requires an internal swap to convert BNB/ETH to USD*, nativeToQuoteSwap must be anabled for this quote token)
/// Note: Currently, this method only supports trading tokens that are still in the bonding curve state.
///       However, in the future, we may also support trading tokens that are already in DEX state.
function swapExactInput(ExactInputParams calldata params) external payable returns (uint256 outputAmount);

This is quite straightforward after getting a quote.

Events

TokenBought

Emitted when a user buys tokens through the Portal.

event TokenBought(
    uint256 ts,
    address token,
    address buyer,
    uint256 amount,
    uint256 eth,
    uint256 fee,
    uint256 postPrice
);

Parameters:

• ts: Timestamp of the trade.

• token: Address of the token bought.

• buyer: Address of the buyer.

• amount: Amount of tokens bought.

• eth: Amount of ETH (or quote token) spent.

• fee: Amount of ETH (or quote token) spent as a fee.

• postPrice: Price of the token after this trade.

When emitted: Whenever a user successfully buys tokens via the Portal.

TokenSold

Emitted when a user sells tokens through the Portal.

event TokenSold(
    uint256 ts,
    address token,
    address seller,
    uint256 amount,
    uint256 eth,
    uint256 fee,
    uint256 postPrice
);

Parameters:

• ts: Timestamp of the trade.

• token: Address of the token sold.

• seller: Address of the seller.

• amount: Amount of tokens sold.

• eth: Amount of ETH (or quote token) received.

• fee: Amount of ETH (or quote token) deducted as a fee.

• postPrice: Price of the token after this trade.

When emitted: Whenever a user successfully sells tokens via the Portal.

FlapTokenProgressChanged

This event is available since v4.12.1

Whenever a token's progress changes, the FlapTokenProgressChanged event will be emitted. Note that the newProgress is in wad (i.e, with 18 decimals, 1 ether = 100%).

/// @notice emitted when the progress of a token changes
/// @param token The address of the token
/// @param newProgress The new progress value in Wad
event FlapTokenProgressChanged(address token, uint256 newProgress);