API

This section will walk you through the required steps to get quote and submit a swap using Mosaic Aggregator.

Swagger

Get Quote

get

Find the best quote to swap with Mosaic Aggregator

Query parameters

srcAssetstringRequiredExample: 0x1::aptos_coin::AptosCoin

dstAssetstringRequiredExample: 0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f::tokens::USDC

amountstringRequired

Amount of the token to be swapped

Example: 100000000

isFeeInbooleanOptional

Whether the fee is in the source asset

Example: true

feeInBpsnumberOptional

Fee in basis points

Example: 30

feeReceiverstringOptional

Fee receiver address

Example: 0x0145f3f2a68d9bcf8f5a1ae2ca34760c76a9742c7b22b36a54f706dd587cc26c

slippagestringOptional

Slippage tolerance in basis points

Example: 10

senderstringOptional

Sender address

Example: 0x0145f3f2a68d9bcf8f5a1ae2ca34760c76a9742c7b22b36a54f706dd587cc26c

receiverstringOptional

Receiver address. If not provided, the sender address will be used.

Example: 0x0145f3f2a68d9bcf8f5a1ae2ca34760c76a9742c7b22b36a54f706dd587cc26c

Header parameters

X-API-KeystringOptional

Responses

200

Successfully found quote

application/json

get

HTTPcURLJavaScriptPython

GET /v1/quote HTTP/1.1
Host: api.mosaic.ag
Accept: */*

200

Successfully found quote

{
  "code": 0,
  "message": "successfully",
  "requestId": "f4f7aa6b2dec13ae9fe36d7622fa83f4",
  "data": {
    "srcAsset": "0x1::aptos_coin::AptosCoin",
    "dstAsset": "0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f::tokens::USDC",
    "srcAmount": 100000,
    "dstAmount": 2056477,
    "feeAmount": 100000,
    "isFeeIn": true,
    "paths": [
      {
        "source": "razor_swap",
        "srcAsset": "0x1::aptos_coin::AptosCoin",
        "dstAsset": "0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f::tokens::USDC",
        "srcAmount": 100000,
        "dstAmount": 2056477
      }
    ],
    "tx": {
      "function": "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::swap",
      "typeArguments": [
        "0x1::aptos_coin::AptosCoin",
        "0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f::tokens::USDC",
        "0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f::tokens::USDT",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null",
        "0xede23ef215f0594e658b148c2a391b1523335ab01495d8637e076ec510c6ec3c::router::Null"
      ],
      "functionArguments": [
        "0x47652bd91e7cf0ca0476eaff712f360addc1edeadd86352f37586183d0278d08",
        [
          "1000000000000"
        ],
        [
          "0",
          "2",
          "1",
          "3",
          "18446744073709551614",
          "0",
          "2",
          "3",
          "4"
        ],
        [
          "0xa"
        ],
        [
          "0x234f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f"
        ],
        "0x0000000000000000000000000000000000000000000000000000000000000000",
        "0",
        false,
        "2000000000000",
        "10",
        "pid",
        "{}"
      ]
    }
  }
}

Get Tokens

get

Retrieve tokens based on IDs, cursor, count, and pattern

Query parameters

idsstring[]Optional

List of token IDs to retrieve. If omit, all tokens will be retrieved.

cursorinteger · uint64Optional

Cursor for pagination.

countinteger · int64Optional

Number of tokens to retrieve.

patternstringOptional

Pattern to match token names.

Header parameters

X-API-KeystringOptional

Responses

200

A list of tokens and the next cursor for pagination.

application/json

get

HTTPcURLJavaScriptPython

GET /v1/tokens HTTP/1.1
Host: api.mosaic.ag
Accept: */*

200

A list of tokens and the next cursor for pagination.

{
  "tokenById": {
    "ANY_ADDITIONAL_PROPERTY": {
      "id": "text",
      "decimals": 1,
      "name": "text",
      "symbol": "text"
    }
  },
  "nextCursor": 1
}

Setup Authentication

All requests to Mosaic’s API must include an X-API-Key header for authentication. The API key is used to track your usage and ensure secure access. To obtain an API key, please contact the Mosaic team via Discord or Telegram or Email

Get quote

To retrieve the best swap rate, send the following HTTP request to get a quote:

curl 'https://api.mosaic.ag/v1/quote?srcAsset=0x1%3A%3Aaptos_coin%3A%3AAptosCoin&dstAsset=0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f%3A%3Atokens%3A%3AUSDC&amount=1000000000&sender=0x0000000000000000000000000000000000000000000000000000000000000000&slippage=10' \
--header 'x-api-key: xxx'

This will return the best available quote for swapping the source asset (AptosCoin) into the destination asset (USDC) based on current market conditions.

Here is a detailed guide using Typescript:

1. Setup Environment

Import the required libraries and initialize your connection to the Aptos testnet using the AptosConfig and Aptos objects from the @aptos-labs/ts-sdk. This sets up your environment for making requests to the Mosaic Aggregator API and interacting with Aptos.

import {
  Account,
  Aptos,
  APTOS_COIN,
  AptosConfig,
  Ed25519PrivateKey,
} from "@aptos-labs/ts-sdk";
import axios from "axios";

// Initialize Aptos config to connect to the testnet
const aptos = new Aptos(
  new AptosConfig({
    fullnode: "https://aptos.testnet.suzuka.movementlabs.xyz/v1",
  })
);

2. Setup User Account

Here, you will create an Aptos account using the user's private key. You need to fill in your own private key when initializing the account.

// Create user account from private key
const user = Account.fromPrivateKey({
  privateKey: new Ed25519PrivateKey(), // TODO: Fill your private key here.
});

3. Define Assets and Amount

Specify the assets to swap and the amount (in APTOS decimals):

const srcAsset = APTOS_COIN; // Source: APTOS Coin
const dstAsset =
  "0x275f508689de8756169d1ee02d889c777de1cebda3a7bbcce63ba8a27c563c6f::tokens::USDC"; // Destination: USDC
const amount = 1_00000000; // Amount: 1 APT (APTOS uses 8 decimals)

4. Get a Quote from Mosaic Aggregator API

Retrieve the best swap rate by making a GET request to the Mosaic API.

// Get a quote from Mosaic Aggregator API
const mosaicResponse = await axios({
  method: "GET",
  url: "https://api.mosaic.ag/v1/quote",
  params: {
    srcAsset,
    dstAsset,
    amount,
    sender: user.accountAddress.toString(),
    slippage: 100, // 100 = 1%
  },
  headers: {
    "X-API-KEY": "xxx", // TODO: Fill the API key in here.
  },
});

5. Build the transaction

Once you have the quote, you use the returned data (function, type arguments, and function arguments) to build a transaction that will perform the swap.

// Build the transaction based on the Mosaic response
const transaction = await aptos.transaction.build.simple({
  sender: user.accountAddress,
  data: {
    function: mosaicResponse.data.data.tx.function,
    typeArguments: mosaicResponse.data.data.tx.typeArguments,
    functionArguments: mosaicResponse.data.data.tx.functionArguments,
  },
});

6. Sign and submit the transaction

After building the transaction, you sign it using the user's private key and submit the transaction to the Aptos blockchain. The transaction hash will be logged, which can be used to check the transaction status on the explorer.

// Sign and submit the transaction
const pendingTransactionResponse =
  await aptos.transaction.signAndSubmitTransaction({
    signer: user,
    transaction: transaction,
  });

// Output transaction URL to the console
console.log(
  `Tx = https://explorer.movementnetwork.xyz/txn/${pendingTransactionResponse.hash}?network=testnet`
);

By following this guide, you will be able to integrate the Mosaic Aggregator API for performing token swaps on the Aptos network. For further assistance or inquiries, feel free to reach out to the Mosaic support team on Discord or Telegram. \