> For the complete documentation index, see [llms.txt](https://docs.coinhall.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coinhall.org/for-developers/hallswap-api.md).

# Hallswap API

## 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](http://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**

### :white\_check\_mark: **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

### :x: **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](https://github.com/coinhall/cosmes) package, but can also be adapted fairly easily to cosm.js or feather.js should you prefer to use them.

```tsx
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

```tsx
// 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`