# Utils

This guide covers additional helper methods for calculations and state checks, such as coin purchase/sale estimation, Bonding Curve progress and etc. These method shall execute through individual coin's Bonding Curve contract.

## Estimate Receiving Amount with Fixed Input Amount

The `getAmountOutAndFee` method estimate the amount to be receive and fee to be paid by specifying an exact input amount. For example, estimating coin amount to be receive with a fixed collateral amount or collateral amount to be receive with specific coin amount.

This method usually used in conjunction with `buyExactIn` and `sellExactIn` method during trading action in Bonding Curve stage.

### Method Interface

```solidity
// solidity interface

/// @notice Estimate amount to receive & fee to pay for an fixed input amount during Bonding Curve stage
///
/// @param _amountIn The fixed input amount of coin/collateral 
/// @param _reserveIn The virtual reserve amount of input type
/// @param _reserveOut The virtual reserve amount of output type
/// @param _paymentTokenIsIn The _amountIn is collateral or not
///
/// @return amountOut The estimated return coin/collateral amount
/// @return fee The platform fee charged
function getAmountOutAndFee(
    uint256 _amountIn,
    uint256 _reserveIn,
    uint256 _reserveOut,
    bool _paymentTokenIsIn
) external view returns (uint256 amountOut, uint256 fee);
```

***

## Estimate Input Amount with Fixed Receiving Amount

The `getAmountInAndFee` method estimate the input amount and fee to be paid by specifying an exact output amount. For example, estimating collateral amount to be pay with a fixed coin amount to be receive.

This method usually used in conjunction with `buyExactOut` and `sellExactOut` method during trading action in Bonding Curve stage.

### Method Interface

```solidity
// solidity interface

/// @notice Estimate input amount & fee to pay for an fixed output amount during Bonding Curve stage
///
/// @param _amountOut The fixed output amount of coin/collateral 
/// @param _reserveIn The virtual reserve amount of output type
/// @param _reserveOut The virtual reserve amount of input type
/// @param _paymentTokenIsIn The _amountIn is collateral or not
///
/// @return amountIn The requred input coin/collateral amount
/// @return fee The platform fee charged
function getAmountInAndFee(
    uint256 _amountOut,
    uint256 _reserveIn,
    uint256 _reserveOut,
    bool _paymentTokenIsOut
) external view returns (uint256 amountIn, uint256 fee);
```

***

## Get Coin Bonding Curve Contract

The `tokenToBondingCurve` mapping in **Basememe Factory** is available to retrieve respective Token's Bonding Curve contract and return it address.

### Method Interface

```solidity
// solidity interface

mapping(address => address) public tokenToBondingCurve;
```

***

## Get Coin Collateral Token

Each Bonding Curve stores the collateral token configured at coin creation. The `collateralToken` method returns the collateral token address.

* `address(0)` means the coin uses native ETH as collateral.
* Otherwise, it returns the ERC20 collateral token address (e.g. USDC / SOL on Base).

### Method Interface

```solidity
// solidity interface

function collateralToken() external view returns (address);
```

***

## Check Coin Bonding Curve Progress

The `getCurveProgressBps` method check coin's current Bonding Curve progress and return in basis point form.

### Method Interface

<pre class="language-solidity"><code class="lang-solidity"><strong>// solidity interface
</strong>
/// @notice Get coin current bonding curve progress
/// 
/// @return progress BPS
function getCurveProgressBps() external view returns (uint256);
</code></pre>

***

## Check Coin Market Cap

The `getMarketCap` method calculate and return coin's current market cap calculated in respective collateral token value. The market cap is only applicable to Bonding Curve stage.

### Method Interface

```solidity
// solidity interface

/// @notice Get coin current market cap in bonding curve
/// 
/// @return market cap in collateral token value 
function getMarketCap() external view returns (uint256);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.base.meme/for-developers/utils.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.