Axiome Trade Contract API

This document describes the public interface of the AMM contract for integration with third‑party applications and services. Message examples are provided in JSON format — exactly as they are sent to

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.

1

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>" }

2

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.

3

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>" }

4

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>" }

5

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.

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).

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.

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.