Hallswap API

Hallswap API allows developers to access liquidity on Hallswap supported chains. Supported chains: Injective, Sei, Archway, Oraichain, Neutron, Terra, Migaloo, Chihuahua

Simulate Swap

GET https://swap.coinhall.org/v1/swap

Simulates and returns the most optimal swap route between any two tokens within a chain. This simulation may route across multiple different pools to maximise returns, and is the same API that the coinhall.org website uses.

Request Query Parameters

• chainId: the chain ID that you wish to swap on. Supported chain IDs include:

  • injective-1

  • pacific-1

  • archway-1

  • Oraichain

  • neutron-1

  • phoenix-1

  • migaloo-1

  • chihuahua-1

• from: the denom or contract address of the asset that is being sold

• to: the denom or contract address of the asset that is being bought

• amount: the on-chain amount of from (ie. must NOT be a floating point number)

• slippageBps: the slippage in basis points (ie. 50 represents 0.5% slippage)

Responses

✅ Success (200 OK)

Returns a JSON with the following fields:

• returnAmount: the expected on-chain amount of to that the caller can expect from executing the swap

• minimumReceive: the minimum on-chain amount of to that the swap must output for the tx to succeed (this is calculated using the given slippageBps)

• contractInput: an object containing the input to the Hallswap contract with the following fields (note that this field is meant to be used as is - check out the examples below):

  • address: the address of the smart contract to run the executeMsg

  • executeMsg: the JSON containing the execute message

  • funds: an array of objects with the following fields:

    • denom: the denom of the asset to send for the swap

    • amount: the on-chain amount of denom to send for the swap

• route: an array of objects with the following fields:

  • returnAsset: an object containing the following fields:

    • symbol: the symbol of the asset that you get from the swap

    • icon: the icon of the asset that you get from the swap

  • dex: the dex that the swap is executed on

❌ Error (400 Bad Request)

Such a response can be expected if:

• chainId is invalid

• from or to does not exist

• from is equal to to

• amount is negative

• slippageBps is bigger than 10000

• No routes are found

Examples

Note that this example uses TypeScript and the CosmES package, but can also be adapted fairly easily to cosm.js or feather.js should you prefer to use them.

import { MsgExecuteContract } from "cosmes/client";
import { CosmosBaseV1beta1Coin } from "cosmes/protobufs";
import { MnemonicWallet } from "cosmes/wallet";

// Simulate swapping 13 USDT to INJ at 1.0% slippage in Injective
const res = await fetch(
  "https://swap.coinhall.org/v1/swap?chainId=injective-1&from=peggy0xdAC17F958D2ee523a2206206994597C13D831ec7&to=inj&amount=13000000&slippageBps=100"
);
const { 
  expectedReturn,
  minimumReceive,
  contractInput,
  route,
} = await res.json();
console.log("Expected return amount", expectedReturn);
console.log("Minimum amount to be received", minimumReceive);
console.log("Route:", route);

// Execute the swap
const wallet = new MnemonicWallet({ /* redacted for brevity */ });
const msgs = [
  new MsgExecuteContract({
    sender: wallet.address,
    contract: contractInput.address,
    msg: contractInput.executeMsg,
    funds: contractInput.funds,
  }),
];
const tx = await wallet.broadcastTxSync({ msgs });
console.log(tx);

Annex: Type Definitions

// The query parameters of the request
type Request = {
  chainId: string;
  to: string;
  from: string;
  amount: string;
  slippageBps: string;
};

// The JSON response from the API
type Response = {
  expectedReturn: string;
  minimumReceive: string;
  contractInput: {
    address: string;
    executeMsg: JSON;
    funds: {
      denom: string;
      amount: string;
    }[];
  };
  route: {
    returnAsset: {
      symbol: string;
      icon?: string | undefined;
    };
    dex: string;
  }[];
};

Annex: Contract Addresses

Hallswap Router Contract (Mainnet)

• Injective: inj16lkekzp36vj6a9zjl778a2s5nd9f6ft67w2e90

• Sei: sei1w5t009q9zr8ky8v84sx9n4r9m6ss9ge7xfkuc6xrh479fjg4qmysrqk4lq

• Archway: archway1tjg47350zpgskprjmcm6chuytnx3q893mru8fqg8jakkw2cjwt5s2unkar

• Oraichain: orai1wl3kn5lx6mf67pqmlefus7ge9wj57e3jyp39mzrhwa4hs00q6e9sp3044z

• Neutron: neutron12k4hr2ecm3c8mjjsn6dc9c043xv8p7v4795qt9g2dwp4nmmlgxdqvz2ujp

• Terra: terra1e3nqr8vwu32pzgasraud9avpwdd8phmqgre5kpwlytgedj2emkkq3l67hy

• Migaloo: migaloo10l2nactp2af8uw3xupgmmpsng85fngguk5jj0qy57vc3lfllan9sarp6hf

• Chihuahua: chihuahua1w029h820yzthj3kqfvv6dzd6h84ys26uxg6x0zd3zmc93kutqe9qrwgsn7