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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coinhall.org/for-developers/hallswap-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.