# Axiome Trade Contract API

## Notation and conventions

* Token denomination: a discriminator object indicating the type of asset. Exactly one of the following forms is used in requests/responses:
  * Native coin of the chain: `{ "native": "<denom>" }`
  * CW20 token: `{ "cw20": "<address>" }`
* Numeric fields:
  * Amounts are strings with integer values in minimal units (e.g., `uatom`, `uosmo`, etc.). No separators.
  * Fee percentages are decimal fractions in the inclusive range \[0, 1], also passed as strings (e.g., "0.003" = 0.3%).
  * Unless explicitly stated otherwise, all amounts are unsigned and specified in minimal units of their denomination.

## Queries (QueryMsg)

The contract supports the following queries. Each entry lists its purpose, request structure, and expected response.

{% stepper %}
{% step %}

### Balance { address }

* Purpose: LP token balance (the contract’s LP token implements CW20 standard).

Request message:

```
{ "balance": { "address": "wasm1...user" } }
```

Response (standard CW20):

```
{ "balance": "<amount>" }
```

{% endstep %}

{% step %}

### Info {}

* Purpose: aggregated pool information — reserves, denominations, LP token address and total supply.

Request message:

```
{ "info": {} }
```

Response:

```
{
  "token1_reserve": "<uint128>",
  "token1_denom": { "native": "..." },
  "token2_reserve": "<uint128>",
  "token2_denom": { "cw20": "..." },
  "lp_token_supply": "<uint128>",
  "lp_token_address": "wasm1...lp"
}
```

Notes:

* `token*_denom` are discriminator objects. Only one key is present: either `native` or `cw20`.
  {% endstep %}

{% step %}

### Token1ForToken2Price { token1\_amount }

* Purpose: get a quote — how much of token2 you will receive for a given amount of token1, accounting for current pool state and fees.

Request message:

```
{ "token1_for_token2_price": { "token1_amount": "1000000" } }
```

Response:

```
{ "token2_amount": "<uint128>" }
```

{% endstep %}

{% step %}

### Token2ForToken1Price { token2\_amount }

* Purpose: reverse quote — how much of token1 you will receive for a given amount of token2.

Request message:

```
{ "token2_for_token1_price": { "token2_amount": "1000000" } }
```

Response:

```
{ "token1_amount": "<uint128>" }
```

{% endstep %}

{% step %}

### Fee {}

* Purpose: current fee settings and owner (if set).

Request message:

```
{ "fee": {} }
```

Response:

```
{
  "owner": "wasm1..." ,
  "lp_fee_percent": "<decimal>",
  "protocol_fee_percent": "<decimal>",
  "protocol_fee_recipient": "wasm1...recipient"
}
```

Notes:

* `owner` may be absent/null depending on the deployment; treat accordingly in your client.
  {% endstep %}
  {% endstepper %}

## How to obtain a swap price

Depending on the direction, use one of the two pricing queries:

* Price Token1 -> Token2:

  ```
  { "token1_for_token2_price": { "token1_amount": "<in_amount>" } }
  ```

  Response:

  ```
  { "token2_amount": "<out_amount>" }
  ```
* Price Token2 -> Token1:

  ```
  { "token2_for_token1_price": { "token2_amount": "<in_amount>" } }
  ```

  Response:

  ```
  { "token1_amount": "<out_amount>" }
  ```

Both quotes are computed by the contract based on the current pool reserves and fee settings (`lp_fee_percent`, `protocol_fee_percent`).

## How to obtain pool reserves and metadata

Call `Info`:

```
{ "info": {} }
```

Check `token1_reserve`, `token2_reserve`, and the denominations `token1_denom`, `token2_denom`. You will also receive the LP token address (`lp_token_address`) and its total supply (`lp_token_supply`).

As a rule of thumb, the spot price is approximately `token1_reserve / token2_reserve` (depending on which way you quote).

## How to obtain current fees

Call `Fee`:

```
{ "fee": {} }
```

The response includes the pool fee percentage and the protocol fee recipient. Percentages are fractions of 1 (e.g., "0.01" = 1%).

## Instantiate message

Message for deploying the contract. Fields and their meaning:

`InstantiateMsg`:

```
{
  "token1_denom": { "native": "..." },
  "token2_denom": { "cw20": "..." },
  "lp_token_code_id": <u64>,
  "owner": "wasm1...",
  "protocol_fee_recipient": "wasm1...",
  "protocol_fee_percent": "<decimal>",
  "lp_fee_percent": "<decimal>"
}
```

Notes:

* `token1_denom`, `token2_denom` — the assets that form the trading pair. Each is a discriminator object with either `native` or `cw20` key.
* `lp_token_code_id` — code ID of the CW20 contract used to mint the pool’s LP token.
* `owner` — admin address (may be null/omitted). Has the right to update fee parameters and owner.
* `protocol_fee_recipient` — recipient of the protocol fee (e.g., community pool).
* `protocol_fee_percent` — protocol fee share (0..1).
* `lp_fee_percent` — pool fee share (0..1).

## Execute messages (ExecuteMsg) — brief

Below are the key execute commands. Full field formats follow the contract schema and examples. If a parameter is marked optional (?), it may be omitted.

* add\_liquidity { token1\_amount, min\_liquidity, max\_token2, expiration? }
  * Adds liquidity to the pool. `min_liquidity` protects against adverse slippage; `max_token2` caps the counter‑asset deposit.
* remove\_liquidity { amount, min\_token1, min\_token2, expiration? }
  * Burns LP tokens and withdraws the share of reserves. Minimums protect against slippage.
* swap { input\_token: "token1"|"token2", input\_amount, min\_output, expiration? }
  * Standard swap. `min_output` is a slippage guard: actual output cannot be less.
* pass\_through\_swap { output\_amm\_address, input\_token, input\_token\_amount, output\_min\_token, expiration? }
  * Pass‑through swap using another AMM as the next hop. Useful for 2+ pool routes.
* swap\_and\_send\_to { input\_token, input\_amount, recipient, min\_token, expiration? }
  * Swap and then send the result to the specified address (e.g., payouts to a user/contract).
* update\_config { owner?, lp\_fee\_percent, protocol\_fee\_percent, protocol\_fee\_recipient }
  * Update fee parameters and owner. Requires owner privileges.
* freeze\_deposits { freeze }
  * Enable/disable accepting new liquidity deposits (administrative).

{% hint style="warning" %}
Security notes:

* It is recommended to always set `min_*` parameters and `expiration` to avoid MEV/slippage and stale quotes.
* For CW20 operations, you may need to perform `approve`/`increase_allowance` per the CW20 standard, depending on your execution environment.
  {% endhint %}

## Quick query examples

* Pool reserves:

  ```
  { "info": {} }
  ```
* Price 1 -> 2 for 1 minimal unit:

  ```
  { "token1_for_token2_price": { "token1_amount": "1" } }
  ```
* Fees:

  ```
  { "fee": {} }
  ```
* LP balance for an address:

  ```
  { "balance": { "address": "wasm1...user" } }
  ```

## Errors and general recommendations

* If input parameters are invalid (e.g., negative values, zero amounts, denomination mismatch), the contract will return an execution error and the transaction will be reverted.
* With low liquidity, the price query may return very small outputs; use `min_*` guards in execute messages.
* To assess slippage, first call the corresponding price query, then form the execute message with a reasonable margin.

## Compatibility and versions

* Message formats are compatible with the CosmWasm ecosystem and assume the standard mechanisms of sending queries/transactions through the network’s RPC/REST services.
* When upgrading the contract, follow the project’s changelog and verify whether field names or semantics have changed.