Aggregator API

Query Superior Swap Rates

Mimboku Aggregator exposes a set of APIs that allows developers to easily query favourable rates for a swap. This includes additional swap data such as the exact swap route, swap routing parameters, as well as the encoded data to be submitted to the Aggregator smart contract. Please refer to Execute A Swap With The Aggregator API for examples on how to integrate with our APIs.

Public API

Environment	URL
Story mainnet	https://router.mimboku.com
Story testnet (Aeneid)	https://router-dev.mimboku.com

Supported Networks

Chain ID	Network
1315	Aeneid Story Testnet
1514	Story Mainnet

API Documentation

Get swap quote

get

https://router-dev.mimboku.comhttps://router.mimboku.com

/quote

Returns the best swap quote based on the provided parameters

Authorizations

ApiKeyAuth

x-client-idstringRequired

Query parameters

tokenInAddressstringRequired

Address of the input token

Example: 0x1514000000000000000000000000000000000000

tokenInChainIdintegerRequired

Chain ID of the input token

Example: 1315

tokenOutAddressstringRequired

Address of the output token

Example: 0xd1fa5456186758b84811b929b4d696178fb56ee3

tokenOutChainIdintegerRequired

Chain ID of the output token

Example: 1315

amountstringRequired

Amount of tokens to swap (in base units)

Example: 100000000000

typestring · enumRequired

Type of quote

Example: exactInPossible values:

protocolsstringOptional

Comma-separated list of protocols to include in the quote, available protocols v2, v3, v3s1, default v3

Example: v2,v3,v3s1,mixed

chainIdinteger · enumOptional

Available Chain IDs:

• 1315: Aeneid Story Testnet
• 1514: Story Mainnet

Example: 1315Possible values:

Responses

200

Successful response with quote information

application/json

blockNumberstringOptional

Current block number when quote was generated

Example: 4172602

amountstringOptional

Amount of tokens to be swapped (in base units)

Example: 10000000000000000000

amountDecimalsstringOptional

Amount with proper decimal formatting

Example: 10

quotestringOptional

The quoted amount for the swap (in base units)

Example: 23380751936294484817899

quoteDecimalsstringOptional

Quote with proper decimal formatting

Example: 23380.751936294484817899

quoteGasAdjustedstringOptional

Quote adjusted for gas costs (in base units)

Example: 23380750164225210864289

quoteGasAdjustedDecimalsstringOptional

Gas-adjusted quote with proper decimal formatting

Example: 23380.750164225210864289

gasUseEstimatestringOptional

Estimated gas usage for the swap

Example: 783000

gasUseEstimateQuotestringOptional

Cost of gas in quote currency (in base units)

Example: 1772069273953609

gasUseEstimateQuoteDecimalsstringOptional

Gas cost with proper decimal formatting

Example: 0.001772069273953609

gasUseEstimateUSDstringOptional

Cost of gas in USD

Example: 0.000003

simulationStatusstring · enumOptional

Status of the transaction simulation

Example: UNATTEMPTEDPossible values:

simulationErrorbooleanOptional

Whether there was an error during simulation

Example: false

gasPriceWeistringOptional

Current gas price in wei

Example: 1000090

routeStringstringOptional

Human-readable representation of the route

Example: [V3] 100.00% = WIP -- 0.05% [0x0bB8Df520A2c1Bf8B50D0a7b326a0Df295069431]USDC.e -- 0.3% [0xFD061584f1F88F24fe11Dfa12B9D283afe2FC9F8]BENJI

quoteIdstringOptional

Unique identifier for this quote

Example: 2674a

hitsCachedRoutesbooleanOptional

Whether the quote used cached route data

Example: false

priceImpactstringOptional

Price impact of the swap as a percentage

Example: 0.1

400

Bad request - invalid parameters

500

Server error

get

/quote

HTTPcURLJavaScriptPython

GET /quote?tokenInAddress=0x1514000000000000000000000000000000000000&tokenInChainId=1315&tokenOutAddress=0xd1fa5456186758b84811b929b4d696178fb56ee3&tokenOutChainId=1315&amount=100000000000&type=exactIn HTTP/1.1
Host: router-dev.mimboku.com
x-client-id: YOUR_API_KEY
Accept: */*

{
  "blockNumber": "4172602",
  "amount": "10000000000000000000",
  "amountDecimals": "10",
  "quote": "23380751936294484817899",
  "quoteDecimals": "23380.751936294484817899",
  "quoteGasAdjusted": "23380750164225210864289",
  "quoteGasAdjustedDecimals": "23380.750164225210864289",
  "gasUseEstimate": "783000",
  "gasUseEstimateQuote": "1772069273953609",
  "gasUseEstimateQuoteDecimals": "0.001772069273953609",
  "gasUseEstimateUSD": "0.000003",
  "simulationStatus": "UNATTEMPTED",
  "simulationError": false,
  "gasPriceWei": "1000090",
  "route": [
    [
      {
        "type": "v3-pool",
        "address": "0x0bB8Df520A2c1Bf8B50D0a7b326a0Df295069431",
        "routerAddress": "0x1062916B1Be3c034C1dC6C26f682Daf1861A3909",
        "dexName": "Storyhunt V3",
        "tokenIn": {
          "chainId": 1514,
          "decimals": "18",
          "address": "0x1514000000000000000000000000000000000000",
          "symbol": "WIP"
        },
        "tokenOut": {
          "chainId": 1514,
          "decimals": "6",
          "address": "0xF1815bd50389c46847f0Bda824eC8da914045D14",
          "symbol": "USDC.e"
        },
        "fee": "500",
        "liquidity": "135625982168192",
        "sqrtRatioX96": "169947854912589181635456",
        "tickCurrent": "-261061",
        "amountIn": "10000000000000000000",
        "amountOut": "23380751936294484817899"
      }
    ]
  ],
  "routeString": "[V3] 100.00% = WIP -- 0.05% [0x0bB8Df520A2c1Bf8B50D0a7b326a0Df295069431]USDC.e -- 0.3% [0xFD061584f1F88F24fe11Dfa12B9D283afe2FC9F8]BENJI",
  "quoteId": "2674a",
  "hitsCachedRoutes": false,
  "priceImpact": "0.1"
}

Example Request

curl --request GET 'https://router-dev.mimboku.com/quote?tokenInAddress=0x1514000000000000000000000000000000000000&tokenInChainId=1315&tokenOutAddress=0xd1fa5456186758b84811b929b4d696178fb56ee3&tokenOutChainId=1315&amount=100000000000&type=exactIn&protocols=v2,v3,v3s1'

Protocols

Protocol	Dex
v2	PiperX V2
v3	StoryHunt V3
v3s1	PiperX V3
mixed	Mixed all dexes PiperX V2, V3 and StoryHunt V3