Aggregator API
The Minswap Aggregator API provides direct access to Minswap's aggregation functionality for partners who want to implement their own interface and control the trading logic.
Currency code to get ADA price in.
usdPossible values: Current ADA price and 24-hour change in USD
The requested currency code in lowercase
usdGET /aggregator/ada-price?currency=usd HTTP/1.1
Host: agg-api.minswap.org
Accept: */*
Current ADA price and 24-hour change in USD
{
"currency": "usd",
"value": {
"change_24h": -2.34,
"price": 0.75
}
}Cardano wallet address to query
- Supports both bech32 and hex format addresses
- Byron (legacy) addresses are not supported
- Will be normalized to bech32 format in response
addr1...If true, all token balances are returned as decimal strings (e.g., "1.5" ADA), not the smallest unit (e.g., "1500000" lovelace). If false or omitted, balances are in smallest unit.
Detailed wallet balance information including ADA and native tokens
The wallet address in bech32 format Example: "addr1..."
addr1...ADA balance.
- 1 ADA = 1,000,000 lovelace
- Returned as string to handle large numbers accurately Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
5000000Minimum required ADA for the wallet. This represents the minimum ADA required to hold native tokens due to the Cardano protocol's UTxO rules. Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Whether amount_in_decimal is enabled or not
GET /aggregator/wallet?address=text HTTP/1.1
Host: agg-api.minswap.org
Accept: */*
Detailed wallet balance information including ADA and native tokens
{
"wallet": "addr1...",
"ada": "5000000",
"minimum_lovelace": "text",
"balance": [
{
"asset": {
"token_id": "text",
"logo": "text",
"ticker": "MIN",
"is_verified": true,
"price_by_ada": 1.5,
"price_by_usd": 0.29,
"project_name": "Minswap",
"decimals": 6
},
"amount": "text"
}
],
"amount_in_decimal": true
}Search for tokens with optional filtering and pagination support. Results can be filtered to only show verified tokens, specific token IDs, or tokens matching a search query.
Search query string to match against:
- Token name (e.g., "Minswap")
- Token ticker (e.g., "MIN")
- Policy ID Empty string returns all tokens (subject to other filters)
minWhen true, returns only tokens verified by Minswap
- true: Only verified tokens
- false: All tokens including unverified ones
trueOptional list of specific token_ids to fetch (at most 100) Format: Array of "" strings Example: ["29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e"]
["29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e"]Pagination cursor from previous response Each page holds up to 20 tokens
Token search results with pagination information
Pagination cursor for the next page Empty when there are no more results
Invalid request body
POST /aggregator/tokens HTTP/1.1
Host: agg-api.minswap.org
Content-Type: application/json
Accept: */*
Content-Length: 136
{
"query": "min",
"only_verified": true,
"assets": [
"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e"
],
"search_after": [
"text"
]
}{
"tokens": [
{
"token_id": "text",
"logo": "text",
"ticker": "MIN",
"is_verified": true,
"price_by_ada": 1.5,
"price_by_usd": 0.29,
"project_name": "Minswap",
"decimals": 6
}
],
"search_after": [
"text"
]
}Find the best possible swap route and price estimation by aggregating liquidity across multiple DEX protocols. Supports direct swaps and multi-hop routing.
Amount of input token.
- If amount_in_decimal is true: amount is a decimal string (e.g., "1.5" ADA)
- If amount_in_decimal is false or omitted: amount is in the smallest unit (e.g., "1500000" lovelace) For ADA: 1 ADA = 1,000,000 lovelace. For other tokens: amount * (10 ^ decimals). Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA or tokens
- "1000000" (with amount_in_decimal=false) means 1 ADA or token with 6 decimals
Input token identifier:
- For ADA: use "lovelace"
- For other tokens: use "" format Example: "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e" for MIN token
lovelaceOutput token identifier:
- For ADA: use "lovelace"
- For other tokens: use "" format Must be different from token_in
29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494eMaximum acceptable slippage percentage:
- Examples: 0.5 means 0.5% slippage tolerance
- Used to calculate min_amount_out
0.5Control whether multi-hop swaps are allowed:
- true: Allow routing through multiple pools to find best price
- false: Only allow direct swaps through a single pool
Multi-hop swaps can often provide better prices by routing through intermediate tokens, but may have higher total fees due to multiple swaps. Example: ADA -> MIN -> iUSD might be more efficient than direct ADA -> iUSD
Control whether routes may chain swap orders across more than one transaction: the output of one swap is sent to the next pool's order contract. These hops are returned in callback_paths.
Partner identifier for tracking and analytics:
- Optional string to identify the partner integration
- Used for volume tracking and potential fee sharing programs
If true, the amount field is interpreted as a decimal string (e.g., "1.5" ADA), not the smallest unit (e.g., "1500000" lovelace). If false or omitted, amount is in smallest unit. Amount must be greater than 0.
Successful route estimation response containing detailed information about:
- Token amounts and minimums
- Fee breakdowns (LP, DEX, and aggregator fees)
- Price impact
- Detailed routing paths through different DEX protocols
Input token identifier (matches request) Example: "lovelace" for ADA
Output token identifier (matches request) Example: "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e" for MIN
Total input amount for the swap. Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Expected output amount This is the estimated amount before slippage Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Minimum output amount considering slippage Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Total LP fees across all pools in the route Sum of all lp_fee values from individual paths Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Total DEX protocol fees across all pools in lovelace Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Total required ADA deposits for output tokens Required by Cardano protocol for holding native tokens Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Average price impact percentage across all pools Lower is better, high values indicate significant market impact Example: 0.5 means 0.5% price impact
Aggregator service fee amount Omitted when no aggregator fee applies Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
Aggregator fee percentage Example: 0.5
Whether amount_in_decimal is enabled or not
POST /aggregator/estimate HTTP/1.1
Host: agg-api.minswap.org
Content-Type: application/json
Accept: */*
Content-Length: 300
{
"amount": "text",
"token_in": "lovelace",
"token_out": "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e",
"slippage": 0.5,
"include_protocols": [
"MinswapV2"
],
"exclude_protocols": [
"MinswapV2"
],
"allow_multi_hops": true,
"allow_non_atomic_multi_hops": true,
"partner": "text",
"amount_in_decimal": true
}Successful route estimation response containing detailed information about:
- Token amounts and minimums
- Fee breakdowns (LP, DEX, and aggregator fees)
- Price impact
- Detailed routing paths through different DEX protocols
{
"token_in": "text",
"token_out": "text",
"amount_in": "text",
"amount_out": "text",
"min_amount_out": "text",
"total_lp_fee": "text",
"total_dex_fee": "text",
"deposits": "text",
"avg_price_impact": 1,
"paths": [
[
{
"pool_id": "text",
"protocol": "MinswapV2",
"lp_token": "text",
"token_in": "text",
"token_out": "text",
"amount_in": "text",
"amount_out": "text",
"min_amount_out": "text",
"lp_fee": "text",
"dex_fee": "text",
"deposits": "text",
"price_impact": 1,
"pool_out_ref": "text",
"callback_paths": [
[
{}
]
]
}
]
],
"aggregator_fee": "text",
"aggregator_fee_percent": 1,
"tokens": {
"ANY_ADDITIONAL_PROPERTY": {
"token_id": "text",
"logo": "text",
"ticker": "MIN",
"is_verified": true,
"price_by_ada": 1.5,
"price_by_usd": 0.29,
"project_name": "Minswap",
"decimals": 6
}
},
"amount_in_decimal": true
}Constructs an unsigned Cardano transaction for performing the swap operation. This endpoint uses the results from /estimate to build a valid transaction that can be signed by the user's wallet and submitted to the network.
The transaction will:
Take tokens from the sender's wallet
Execute swaps through specified DEX protocols
Return output tokens to the sender
Handle all necessary ADA deposits and fee payments
Cardano wallet address that will:
- Provide the input tokens
- Pay transaction fees
- Receive output tokens
Minimum acceptable output amount The route is estimated again when the transaction is built; the request fails if the new min_amount_out is lower than this value Examples:
- "1.5" (with amount_in_decimal=true) means 1.5 ADA
- "1000000" (with amount_in_decimal=false) means 1 ADA
If true, the amount in the estimate is interpreted as a decimal string (e.g., "1.5" ADA), not the smallest unit (e.g., "1500000" lovelace). If false or omitted, amount is in smallest unit.
Optional list of hex-encoded CBOR UTxOs to build the transaction from If omitted, the sender's UTxOs are used
Successfully built unsigned transaction The returned CBOR can be signed by the sender's wallet
Unsigned transaction in CBOR format This can be:
- Signed using the sender's wallet
- Submitted to /finalize-and-submit-tx with witness data
Example: "84a400..." (hex-encoded CBOR)
POST /aggregator/build-tx HTTP/1.1
Host: agg-api.minswap.org
Content-Type: application/json
Accept: */*
Content-Length: 369
{
"sender": "text",
"min_amount_out": "text",
"estimate": {
"amount": "text",
"token_in": "text",
"token_out": "text",
"slippage": 1,
"include_protocols": [
"MinswapV2"
],
"exclude_protocols": [
"MinswapV2"
],
"allow_multi_hops": true,
"allow_non_atomic_multi_hops": true,
"partner": "text"
},
"amount_in_decimal": true,
"extra_output": {
"address": "text",
"lovelace": "text"
},
"inputs_to_choose": [
"text"
]
}Successfully built unsigned transaction The returned CBOR can be signed by the sender's wallet
{
"cbor": "text"
}Submits a signed transaction to the Cardano network. This endpoint should be called after getting the unsigned transaction from /build-tx and signing it with the sender's wallet.
The endpoint will:
Validate the transaction and witness data
Submit the transaction to the Cardano network
Return the transaction ID for tracking
Unsigned transaction CBOR from /build-tx response Must be the exact CBOR string received, unmodified Example: "84a400..." (hex-encoded CBOR)
Witness data containing the transaction signature Generated by the sender's wallet when signing Must be hex-encoded Example: "a100..." (hex-encoded witness data)
Transaction successfully submitted to the network The transaction will be processed in the next available block
Transaction ID (hash) for tracking Can be used to:
- Monitor transaction status
- Look up transaction on block explorers Example: "1abc..." (hex-encoded transaction hash)
POST /aggregator/finalize-and-submit-tx HTTP/1.1
Host: agg-api.minswap.org
Content-Type: application/json
Accept: */*
Content-Length: 36
{
"cbor": "text",
"witness_set": "text"
}Transaction successfully submitted to the network The transaction will be processed in the next available block
{
"tx_id": "text"
}Retrieves all pending swap orders for a given wallet address across different DEX protocols. This endpoint is useful for:
Finding orders that need to be cancelled
Tracking pending transactions
Orders remain pending until they are either:
Filled (swap completed)
Cancelled (using /cancel-tx)
Expired (if the DEX protocol supports expiration)
Cardano wallet address to query pending orders for Must be in bech32 format Example: "addr1..."
If true, all token amounts are returned as decimal strings (e.g., "1.5" ADA), not the smallest unit (e.g., "1500000" lovelace). If false or omitted, amounts are in smallest unit.
Successfully retrieved pending orders Returns an empty array if no pending orders exist
Whether amount_in_decimal is enabled or not
GET /aggregator/pending-orders?owner_address=text HTTP/1.1
Host: agg-api.minswap.org
Accept: */*
Successfully retrieved pending orders Returns an empty array if no pending orders exist
{
"orders": [
{
"owner_address": "text",
"protocol": "MinswapV2",
"token_in": {
"token_id": "text",
"logo": "text",
"ticker": "MIN",
"is_verified": true,
"price_by_ada": 1.5,
"price_by_usd": 0.29,
"project_name": "Minswap",
"decimals": 6
},
"token_out": {
"token_id": "text",
"logo": "text",
"ticker": "MIN",
"is_verified": true,
"price_by_ada": 1.5,
"price_by_usd": 0.29,
"project_name": "Minswap",
"decimals": 6
},
"amount_in": "text",
"min_amount_out": "text",
"created_at": 1,
"tx_in": "text",
"dex_fee": "text",
"deposit": "text"
}
],
"amount_in_decimal": true
}Builds an unsigned transaction that cancels pending swap orders. This is useful when:
A swap transaction is stuck or pending
You want to reclaim tokens from an unfilled order
You want to cancel multiple orders at once
Supports cancelling orders across multiple DEX protocols Can cancel up to 6 orders in a single transaction
Cardano wallet address that:
- Originally created the orders
- Will receive refunded tokens
Must be in bech32 format Example: "addr1..."
Successfully built unsigned cancellation transaction The returned CBOR can be signed by the sender's wallet
Unsigned transaction in CBOR format This can be:
- Signed using the sender's wallet
- Submitted to /finalize-and-submit-tx with witness data
Example: "84a400..." (hex-encoded CBOR)
POST /aggregator/cancel-tx HTTP/1.1
Host: agg-api.minswap.org
Content-Type: application/json
Accept: */*
Content-Length: 45
{
"sender": "text",
"orders": [
{
"tx_in": "text"
}
]
}Successfully built unsigned cancellation transaction The returned CBOR can be signed by the sender's wallet
{
"cbor": "text"
}Last updated