@yoroi/swap
Version:
The Swap package of Yoroi SDK
1,115 lines (1,090 loc) • 49.9 kB
Markdown
# Aggregator API
## GET /ada-price
> Get current ADA price in multiple currencies
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/ada-price": {
"get": {
"summary": "Get current ADA price in multiple currencies",
"parameters": [
{
"name": "currency",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"aed",
"ars",
"aud",
"bdt",
"bhd",
"bmd",
"brl",
"cad",
"chf",
"clp",
"cny",
"czk",
"dkk",
"eur",
"gbp",
"hkd",
"huf",
"idr",
"ils",
"inr",
"jpy",
"krw",
"kwd",
"lkr",
"mmk",
"mxn",
"myr",
"ngn",
"nok",
"nzd",
"php",
"pkr",
"pln",
"rub",
"sar",
"sek",
"sgd",
"thb",
"try",
"twd",
"uah",
"usd",
"vef",
"vnd",
"xdr",
"zar"
]
},
"description": "Currency code to get ADA price in.\nCommon values: usd, eur, jpy.\n"
}
],
"responses": {
"200": {
"description": "Current ADA price and 24-hour change in requested currency",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "The requested currency code in lowercase\nExample: \"usd\", \"eur\", \"gbp\"\n"
},
"value": {
"type": "object",
"nullable": true,
"description": "Price information (null if price data unavailable)\n",
"properties": {
"change_24h": {
"type": "number",
"description": "24-hour price change percentage\n- Positive value: price increased\n- Negative value: price decreased\nExample: -2.34 means price dropped 2.34%\n"
},
"price": {
"type": "number",
"description": "Current price in the requested currency\nExample: 0.75 means 1 ADA = $0.75 USD\n"
}
}
}
}
}
}
}
}
}
}
}
}
}
```
## GET /wallet
> Query wallet balances and token information
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/wallet": {
"get": {
"summary": "Query wallet balances and token information",
"parameters": [
{
"name": "address",
"in": "query",
"required": true,
"schema": {"type": "string"},
"description": "Cardano wallet address to query\n- Supports both Cbor and Hex format addresses\n- Will be normalized to Cbor format in response\n"
},
{
"name": "amount_in_decimal",
"in": "query",
"required": false,
"schema": {"type": "boolean"},
"description": "If true, all token balances are returned as decimal strings (e.g., \"1.5\" ADA),\nnot the smallest unit (e.g., \"1500000\" lovelace). If false or omitted, balances are in smallest unit.\n"
}
],
"responses": {
"200": {
"description": "Detailed wallet balance information including ADA and native tokens",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"wallet": {
"type": "string",
"description": "The wallet address in cbor format\nExample: \"addr1...\"\n"
},
"ada": {
"type": "string",
"description": "ADA balance.\n- 1 ADA = 1,000,000 lovelace\n- Returned as string to handle large numbers accurately\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"minimum_lovelace": {
"type": "string",
"description": "Minimum required ADA for the wallet.\nThis represents the minimum ADA required to hold native tokens due to the Cardano protocol's UTxO rules.\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"balance": {
"type": "array",
"description": "Array of token balances held in the wallet.\nEach entry represents a different token's balance and metadata.\nADA (lovelace) is not included here as it has its own field 'ada'.\n",
"items": {
"type": "object",
"description": "Token balance entry with asset information",
"properties": {
"asset": {
"$ref": "#/components/schemas/Asset",
"description": "Detailed information about the token"
},
"amount": {
"type": "string",
"description": "Token balance\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\nNote: Always returned as string to handle large numbers accurately\n"
}
}
}
},
"amount_in_decimal": {
"type": "boolean",
"description": "Whether amount_in_decimal is enabled or not"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Asset": {
"type": "object",
"required": ["token_id"],
"properties": {
"token_id": {
"type": "string",
"description": "Token identifier, two possible formats:\n- For ADA: use \"lovelace\"\n- For other tokens: concatenate <policyId><tokenName> in hex\nExample: \"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e\" for MIN token\n"
},
"logo": {
"type": "string",
"nullable": true,
"description": "Logo url of the token\nCan be null if no logo is available\n"
},
"ticker": {
"type": "string",
"nullable": true,
"description": "Token ticker symbol (if available)\nCan be null for tokens without a ticker symbol\nExample: \"MIN\", \"iUSD\", \"DJED\"\n"
},
"is_verified": {
"type": "boolean",
"nullable": true,
"description": "Token verification status on Minswap\n- true: Token is verified by Minswap\n- false: Token is not verified\n- null: Verification status unknown\n"
},
"price_by_ada": {
"type": "number",
"nullable": true,
"description": "Token price denominated in ADA\nCan be null if price information is unavailable\nExample: 1.5 means 1 token = 1.5 ADA\n"
},
"project_name": {
"type": "string",
"nullable": true,
"description": "Name of the project that issued the token\nCan be null for unknown projects\nExample: \"Minswap\", \"Indigo\"\n"
},
"decimals": {
"type": "number",
"nullable": true,
"description": "Number of decimal places for the token\n- ADA always has 6 decimals (1 ADA = 1,000,000 lovelace)\n- Most tokens follow the 6 decimal standard\n- Can be null for tokens with unknown decimals\nExample: 6 means divide by 1,000,000 to get actual amount\n"
}
}
}
}
}
}
```
## Search and filter token information with pagination
> 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.\\
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/tokens": {
"post": {
"summary": "Search and filter token information with pagination",
"description": "Search for tokens with optional filtering and pagination support. Results can be filtered\nto only show verified tokens, specific token IDs, or tokens matching a search query.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["query", "only_verified"],
"properties": {
"query": {
"type": "string",
"description": "Search query string to match against:\n- Token name (e.g., \"Minswap\")\n- Token ticker (e.g., \"MIN\")\n- Policy ID\nEmpty string returns all tokens (subject to other filters)\n"
},
"only_verified": {
"type": "boolean",
"description": "When true, returns only tokens verified by Minswap\n- true: Only verified tokens\n- false: All tokens including unverified ones\n"
},
"assets": {
"type": "array",
"items": {"type": "string"},
"description": "Optional list of specific token_ids to fetch\nFormat: Array of \"<policyId><tokenName>\" strings\nExample: [\"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e\"]\n"
},
"search_after": {
"type": "array",
"items": {"type": "string"},
"description": "Pagination cursor from previous response\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Token search results with pagination information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tokens": {
"type": "array",
"description": "Array of tokens matching the search criteria.\nMay be empty if no tokens match or all are filtered out.\n",
"items": {"$ref": "#/components/schemas/Asset"}
},
"search_after": {
"type": "array",
"items": {"type": "string"},
"description": "Pagination cursor for the next page\n"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Asset": {
"type": "object",
"required": ["token_id"],
"properties": {
"token_id": {
"type": "string",
"description": "Token identifier, two possible formats:\n- For ADA: use \"lovelace\"\n- For other tokens: concatenate <policyId><tokenName> in hex\nExample: \"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e\" for MIN token\n"
},
"logo": {
"type": "string",
"nullable": true,
"description": "Logo url of the token\nCan be null if no logo is available\n"
},
"ticker": {
"type": "string",
"nullable": true,
"description": "Token ticker symbol (if available)\nCan be null for tokens without a ticker symbol\nExample: \"MIN\", \"iUSD\", \"DJED\"\n"
},
"is_verified": {
"type": "boolean",
"nullable": true,
"description": "Token verification status on Minswap\n- true: Token is verified by Minswap\n- false: Token is not verified\n- null: Verification status unknown\n"
},
"price_by_ada": {
"type": "number",
"nullable": true,
"description": "Token price denominated in ADA\nCan be null if price information is unavailable\nExample: 1.5 means 1 token = 1.5 ADA\n"
},
"project_name": {
"type": "string",
"nullable": true,
"description": "Name of the project that issued the token\nCan be null for unknown projects\nExample: \"Minswap\", \"Indigo\"\n"
},
"decimals": {
"type": "number",
"nullable": true,
"description": "Number of decimal places for the token\n- ADA always has 6 decimals (1 ADA = 1,000,000 lovelace)\n- Most tokens follow the 6 decimal standard\n- Can be null for tokens with unknown decimals\nExample: 6 means divide by 1,000,000 to get actual amount\n"
}
}
}
}
}
}
```
## Get optimal swap route and price estimation across DEX protocols
> Find the best possible swap route and price estimation by aggregating liquidity\
> across multiple DEX protocols. Supports direct swaps and multi-hop routing.\\
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/estimate": {
"post": {
"summary": "Get optimal swap route and price estimation across DEX protocols",
"description": "Find the best possible swap route and price estimation by aggregating liquidity\nacross multiple DEX protocols. Supports direct swaps and multi-hop routing.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["amount", "token_in", "token_out", "slippage"],
"properties": {
"amount": {
"type": "string",
"description": "Amount of input token.\n- If amount_in_decimal is true: amount is a decimal string (e.g., \"1.5\" ADA)\n- If amount_in_decimal is false or omitted: amount is in the smallest unit (e.g., \"1500000\" lovelace)\nFor ADA: 1 ADA = 1,000,000 lovelace.\nFor other tokens: amount * (10 ^ decimals).\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA or tokens\n- \"1000000\" (with amount_in_decimal=false) means 1 ADA or token with 6 decimals\n"
},
"token_in": {
"type": "string",
"description": "Input token identifier:\n- For ADA: use \"lovelace\"\n- For other tokens: use \"<policyId><tokenName>\" format\nExample: \"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e\" for MIN token\n"
},
"token_out": {
"type": "string",
"description": "Output token identifier:\n- For ADA: use \"lovelace\"\n- For other tokens: use \"<policyId><tokenName>\" format\nMust be different from token_in\n"
},
"slippage": {
"type": "number",
"description": "Maximum acceptable slippage percentage:\n- Examples: 0.5 means 0.5% slippage tolerance\n- Used to calculate min_amount_out\n"
},
"include_protocols": {
"type": "array",
"items": {"$ref": "#/components/schemas/Protocol"},
"description": "Optional list of DEX protocols to include from routing:\n- Useful for choosing specific DEXs\n- Minswap protocols are always included\n- This overrides exclude_protocols if both are provided\n"
},
"exclude_protocols": {
"type": "array",
"items": {"$ref": "#/components/schemas/Protocol"},
"description": "Optional list of DEX protocols to exclude from routing:\n- Useful for avoiding specific DEXs\n- Minswap protocols cannot be excluded\n"
},
"allow_multi_hops": {
"type": "boolean",
"description": "Control whether multi-hop swaps are allowed:\n- true: Allow routing through multiple pools to find best price\n- false: Only allow direct swaps through a single pool\n\nMulti-hop swaps can often provide better prices by routing through \nintermediate tokens, but may have higher total fees due to multiple swaps.\nExample: ADA -> MIN -> iUSD might be more efficient than direct ADA -> iUSD\n"
},
"partner": {
"type": "string",
"description": "Partner identifier for tracking and analytics:\n- Optional string to identify the partner integration\n- Used for volume tracking and potential fee sharing programs\n"
},
"amount_in_decimal": {
"type": "boolean",
"description": "If true, the amount field is interpreted as a decimal string (e.g., \"1.5\" ADA),\nnot the smallest unit (e.g., \"1500000\" lovelace). If false or omitted, amount is in smallest unit.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful route estimation response containing detailed information about:\n- Token amounts and minimums\n- Fee breakdowns (LP, DEX, and aggregator fees)\n- Price impact\n- Detailed routing paths through different DEX protocols\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"token_in": {
"type": "string",
"description": "Input token identifier (matches request)\nExample: \"lovelace\" for ADA\n"
},
"token_out": {
"type": "string",
"description": "Output token identifier (matches request)\nExample: \"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e\" for MIN\n"
},
"amount_in": {
"type": "string",
"description": "Total input amount for the swap.\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"amount_out": {
"type": "string",
"description": "Expected output amount\nThis is the estimated amount before slippage\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"min_amount_out": {
"type": "string",
"description": "Minimum output amount considering slippage\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"total_lp_fee": {
"type": "string",
"description": "Total LP fees across all pools in the route\nSum of all lp_fee values from individual paths\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"total_dex_fee": {
"type": "string",
"description": "Total DEX protocol fees across all pools in lovelace\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"deposits": {
"type": "string",
"description": "Total required ADA deposits for output tokens\nRequired by Cardano protocol for holding native tokens\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"avg_price_impact": {
"type": "number",
"description": "Average price impact percentage across all pools\nLower is better, high values indicate significant market impact\nExample: 0.5 means 0.5% price impact\n"
},
"paths": {
"type": "array",
"description": "Detailed routing information through DEX pools\nFor multi-hop routes, contains multiple hops\nFor direct swaps, contains a single hop\n",
"items": {
"type": "array",
"description": "Array of hops in the route\nEach array represents one complete path from input to output token\n",
"items": {
"type": "object",
"description": "Individual swap/hop information through a specific pool\n",
"properties": {
"pool_id": {
"type": "string",
"description": "Unique identifier for the liquidity pool\nFormat varies by protocol\n"
},
"protocol": {
"$ref": "#/components/schemas/Protocol",
"description": "DEX protocol used for this hop\nEach protocol may have different fee structures\n"
},
"lp_token": {
"type": "string",
"description": "Liquidity pool token identifier\n"
},
"token_in": {
"type": "string",
"description": "Input token for this specific hop\nFor multi-hop routes, may be different from overall token_in\n"
},
"token_out": {
"type": "string",
"description": "Output token for this specific hop\nFor multi-hop routes, may be different from overall token_out\n"
},
"amount_in": {
"type": "string",
"description": "Input amount for this hop\nFor multi-hop routes, output of previous hop\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"amount_out": {
"type": "string",
"description": "Expected output amount for this hop\nFor final hop, contributes to overall amount_out\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"min_amount_out": {
"type": "string",
"description": "Minimum output amount for this hop with slippage\nEnsures each hop meets minimum requirements\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"lp_fee": {
"type": "string",
"description": "LP fee amount for this hop\nPaid to liquidity providers\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"dex_fee": {
"type": "string",
"description": "Protocol fee amount for this hop\nPaid to the DEX protocol\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"deposits": {
"type": "string",
"description": "Required ADA deposit for this hop\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"price_impact": {
"type": "number",
"description": "Price impact percentage for this specific hop\nLower values indicate better pricing\n"
}
}
}
}
},
"aggregator_fee": {
"type": "string",
"description": "Aggregator service fee amount\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"aggregator_fee_percent": {
"type": "number",
"description": "Aggregator fee percentage\nExample: 0.5\n"
},
"amount_in_decimal": {
"type": "boolean",
"description": "Whether amount_in_decimal is enabled or not"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Protocol": {
"type": "string",
"enum": [
"MinswapV2",
"Minswap",
"MinswapStable",
"MuesliSwap",
"Splash",
"SundaeSwapV3",
"SundaeSwap",
"VyFinance",
"CswapV1",
"WingRidersV2",
"WingRiders",
"WingRidersStableV2",
"Spectrum",
"SplashStable"
]
}
}
}
}
```
## Build unsigned swap transaction
> 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:\
> 1\. Take tokens from the sender's wallet\
> 2\. Execute swaps through specified DEX protocols\
> 3\. Return output tokens to the sender\
> 4\. Handle all necessary ADA deposits and fee payments\\
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/build-tx": {
"post": {
"summary": "Build unsigned swap transaction",
"description": "Constructs an unsigned Cardano transaction for performing the swap operation.\nThis endpoint uses the results from /estimate to build a valid transaction\nthat can be signed by the user's wallet and submitted to the network.\n\nThe transaction will:\n1. Take tokens from the sender's wallet\n2. Execute swaps through specified DEX protocols\n3. Return output tokens to the sender\n4. Handle all necessary ADA deposits and fee payments\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sender": {
"type": "string",
"description": "Cardano wallet address that will:\n- Provide the input tokens\n- Pay transaction fees\n- Receive output tokens\n"
},
"min_amount_out": {
"type": "string",
"description": "Minimum acceptable output amount\nMust be greater than or equal to the min_amount_out\nfrom the /estimate response to ensure price protection\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"estimate": {
"type": "object",
"description": "Swap parameters matching a previous /estimate call\nThe transaction will be built according to these parameters\nMust match the exact values used in /estimate to ensure\nthe route and pricing remain valid\n",
"properties": {
"amount": {
"type": "string",
"description": "Amount of input tokens\nMust match the amount used in /estimate\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"token_in": {
"type": "string",
"description": "Input token identifier\nMust match the token_in used in /estimate\nExample: \"lovelace\" for ADA\n"
},
"token_out": {
"type": "string",
"description": "Output token identifier\nMust match the token_out used in /estimate\nExample: \"<policy_id><asset_name>\" for native tokens\n"
},
"slippage": {
"type": "number",
"description": "Maximum acceptable slippage percentage\nMust match the slippage used in /estimate\nExample: 0.5 for 0.5% slippage tolerance\n"
},
"include_protocols": {
"type": "array",
"items": {"$ref": "#/components/schemas/Protocol"},
"description": "Optional list of DEX protocols to include\nMust match include_protocols used in /estimate\n"
},
"exclude_protocols": {
"type": "array",
"items": {"$ref": "#/components/schemas/Protocol"},
"description": "Optional list of DEX protocols to exclude\nMust match exclude_protocols used in /estimate\n"
},
"allow_multi_hops": {
"type": "boolean",
"description": "Whether to allow multi-hop routes\nMust match allow_multi_hops used in /estimate\n"
},
"partner": {
"type": "string",
"description": "Partner identifier for fee tracking\nMust match partner used in /estimate if provided\n"
}
}
},
"inputs_to_choose": {
"type": "array",
"description": "Optional list of preferred UTxO inputs to use when building the transaction.\n",
"items": {"type": "string"}
},
"amount_in_decimal": {
"type": "boolean",
"description": "If true, the amount in the estimate is interpreted as a decimal string (e.g., \"1.5\" ADA),\nnot the smallest unit (e.g., \"1500000\" lovelace). If false or omitted, amount is in smallest unit.\n"
}
},
"required": ["sender", "min_amount_out", "estimate"]
}
}
}
},
"responses": {
"200": {
"description": "Successfully built unsigned transaction\nThe returned CBOR can be signed by the sender's wallet\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cbor": {
"type": "string",
"description": "Unsigned transaction in CBOR format\nThis can be:\n1. Signed using the sender's wallet\n2. Submitted to /finalize-and-submit-tx with witness data\n\nExample: \"84a400...\" (hex-encoded CBOR)\n"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Protocol": {
"type": "string",
"enum": [
"MinswapV2",
"Minswap",
"MinswapStable",
"MuesliSwap",
"Splash",
"SundaeSwapV3",
"SundaeSwap",
"VyFinance",
"CswapV1",
"WingRidersV2",
"WingRiders",
"WingRidersStableV2",
"Spectrum",
"SplashStable"
]
}
}
}
}
```
## Submit signed transaction to network
> 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:\
> 1\. Validate the transaction and witness data\
> 2\. Submit the transaction to the Cardano network\
> 3\. Return the transaction ID for tracking\\
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/finalize-and-submit-tx": {
"post": {
"summary": "Submit signed transaction to network",
"description": "Submits a signed transaction to the Cardano network. This endpoint should be called\nafter getting the unsigned transaction from /build-tx and signing it with the sender's wallet.\n\nThe endpoint will:\n1. Validate the transaction and witness data\n2. Submit the transaction to the Cardano network\n3. Return the transaction ID for tracking\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cbor": {
"type": "string",
"description": "Unsigned transaction CBOR from /build-tx response\nMust be the exact CBOR string received, unmodified\nExample: \"84a400...\" (hex-encoded CBOR)\n"
},
"witness_set": {
"type": "string",
"description": "Witness data containing the transaction signature\nGenerated by the sender's wallet when signing\nMust be hex-encoded\nExample: \"a100...\" (hex-encoded witness data)\n"
}
},
"required": ["cbor", "witness_set"]
}
}
}
},
"responses": {
"200": {
"description": "Transaction successfully submitted to the network\nThe transaction will be processed in the next available block\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tx_id": {
"type": "string",
"description": "Transaction ID (hash) for tracking\nCan be used to:\n- Monitor transaction status\n- Look up transaction on block explorers\nExample: \"1abc...\" (hex-encoded transaction hash)\n"
}
}
}
}
}
}
}
}
}
}
}
```
## Get list of pending swap orders for a wallet
> 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)\\
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/pending-orders": {
"get": {
"summary": "Get list of pending swap orders for a wallet",
"description": "Retrieves all pending swap orders for a given wallet address across different DEX protocols.\nThis endpoint is useful for:\n- Finding orders that need to be cancelled\n- Tracking pending transactions\n\nOrders remain pending until they are either:\n- Filled (swap completed)\n- Cancelled (using /cancel-tx)\n- Expired (if the DEX protocol supports expiration)\n",
"parameters": [
{
"name": "owner_address",
"in": "query",
"required": true,
"schema": {"type": "string"},
"description": "Cardano wallet address to query pending orders for\nMust be in bech32 format\nExample: \"addr1...\"\n"
},
{
"name": "amount_in_decimal",
"in": "query",
"required": false,
"schema": {"type": "boolean"},
"description": "If true, all token amounts are returned as decimal strings (e.g., \"1.5\" ADA),\nnot the smallest unit (e.g., \"1500000\" lovelace). If false or omitted, amounts are in smallest unit.\n"
}
],
"responses": {
"200": {
"description": "Successfully retrieved pending orders\nReturns an empty array if no pending orders exist\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"orders": {
"type": "array",
"description": "List of pending orders for the wallet\n",
"items": {
"type": "object",
"properties": {
"owner_address": {
"type": "string",
"description": "Wallet address that created the order"
},
"protocol": {
"$ref": "#/components/schemas/Protocol",
"description": "DEX protocol where the order was placed"
},
"token_in": {
"$ref": "#/components/schemas/Asset",
"description": "Token being sold in this order"
},
"token_out": {
"$ref": "#/components/schemas/Asset",
"description": "Token being bought in this order"
},
"amount_in": {
"type": "string",
"description": "Amount of input token committed to the order\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"min_amount_out": {
"type": "string",
"description": "Minimum amount of output token to receive\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"created_at": {
"type": "number",
"description": "Unix timestamp (ms) when the order was created"
},
"tx_in": {
"type": "string",
"description": "Transaction input pointer (TxHash#Index) for the order"
},
"dex_fee": {
"type": "string",
"description": "DEX protocol fee amount\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
},
"deposit": {
"type": "string",
"description": "Required ADA deposit amount\nExamples:\n- \"1.5\" (with amount_in_decimal=true) means 1.5 ADA \n- \"1000000\" (with amount_in_decimal=false) means 1 ADA\n"
}
},
"required": [
"owner_address",
"protocol",
"token_in",
"token_out",
"amount_in",
"min_amount_out",
"created_at",
"tx_in",
"dex_fee",
"deposit"
]
}
},
"amount_in_decimal": {
"type": "boolean",
"description": "Whether amount_in_decimal is enabled or not"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Protocol": {
"type": "string",
"enum": [
"MinswapV2",
"Minswap",
"MinswapStable",
"MuesliSwap",
"Splash",
"SundaeSwapV3",
"SundaeSwap",
"VyFinance",
"CswapV1",
"WingRidersV2",
"WingRiders",
"WingRidersStableV2",
"Spectrum",
"SplashStable"
]
},
"Asset": {
"type": "object",
"required": ["token_id"],
"properties": {
"token_id": {
"type": "string",
"description": "Token identifier, two possible formats:\n- For ADA: use \"lovelace\"\n- For other tokens: concatenate <policyId><tokenName> in hex\nExample: \"29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e\" for MIN token\n"
},
"logo": {
"type": "string",
"nullable": true,
"description": "Logo url of the token\nCan be null if no logo is available\n"
},
"ticker": {
"type": "string",
"nullable": true,
"description": "Token ticker symbol (if available)\nCan be null for tokens without a ticker symbol\nExample: \"MIN\", \"iUSD\", \"DJED\"\n"
},
"is_verified": {
"type": "boolean",
"nullable": true,
"description": "Token verification status on Minswap\n- true: Token is verified by Minswap\n- false: Token is not verified\n- null: Verification status unknown\n"
},
"price_by_ada": {
"type": "number",
"nullable": true,
"description": "Token price denominated in ADA\nCan be null if price information is unavailable\nExample: 1.5 means 1 token = 1.5 ADA\n"
},
"project_name": {
"type": "string",
"nullable": true,
"description": "Name of the project that issued the token\nCan be null for unknown projects\nExample: \"Minswap\", \"Indigo\"\n"
},
"decimals": {
"type": "number",
"nullable": true,
"description": "Number of decimal places for the token\n- ADA always has 6 decimals (1 ADA = 1,000,000 lovelace)\n- Most tokens follow the 6 decimal standard\n- Can be null for tokens with unknown decimals\nExample: 6 means divide by 1,000,000 to get actual amount\n"
}
}
}
}
}
}
```
## Build transaction to cancel pending orders
> 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\\
```json
{
"openapi": "3.0.0",
"info": {"title": "Minswap Aggregator API Documentation", "version": "1.0.0"},
"servers": [
{
"url": "https://agg-api.minswap.org/aggregator",
"description": "Production server"
}
],
"paths": {
"/cancel-tx": {
"post": {
"summary": "Build transaction to cancel pending orders",
"description": "Builds an unsigned transaction that cancels pending swap orders.\nThis is useful when:\n- A swap transaction is stuck or pending\n- You want to reclaim tokens from an unfilled order\n- You want to cancel multiple orders at once\n\nSupports cancelling orders across multiple DEX protocols\nCan cancel up to 6 orders in a single transaction\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sender": {
"type": "string",
"description": "Cardano wallet address that:\n- Originally created the orders\n- Will receive refunded tokens\n\nMust be in bech32 format\nExample: \"addr1...\"\n"
},
"orders": {
"type": "array",
"description": "List of orders to cancel\nEach order must belong to the sender\nOrders are processed in the given order\n",
"minItems": 1,
"maxItems": 6,
"items": {
"type": "object",
"description": "Individual order cancellation details",
"properties": {
"tx_in": {
"type": "string",
"description": "Transaction input pointer (TxHash#Index) for the order\nFormat: \"<transaction_hash>#<output_index>\"\nExample: \"1abc...#0\"\n"
},
"protocol": {
"$ref": "#/components/schemas/Protocol",
"description": "DEX protocol where the order was placed\nMust match the protocol used to create the order\n"
}
},
"required": ["tx_in", "protocol"]
}
}
},
"required": ["sender", "orders"]
}
}
}
},
"responses": {
"200": {
"description": "Successfully built unsigned cancellation transaction\nThe returned CBOR can be signed by the sender's wallet\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cbor": {
"type": "string",
"description": "Unsigned transaction in CBOR format\nThis can be:\n1. Signed using the sender's wallet\n2. Submitted to /finalize-and-submit-tx with witness data\n\nExample: \"84a400...\" (hex-encoded CBOR)\n"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Protocol": {
"type": "string",
"enum": [
"MinswapV2",
"Minswap",
"MinswapStable",
"MuesliSwap",
"Splash",
"SundaeSwapV3",
"SundaeSwap",
"VyFinance",
"CswapV1",
"WingRidersV2",
"WingRiders",
"WingRidersStableV2",
"Spectrum",
"SplashStable"
]
}
}
}
}
```