# 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": "" }` * CW20 token: `{ "cw20": "
" }` * 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": "" } ``` {% endstep %} {% step %} ### Info {} * Purpose: aggregated pool information — reserves, denominations, LP token address and total supply. Request message: ``` { "info": {} } ``` Response: ``` { "token1_reserve": "", "token1_denom": { "native": "..." }, "token2_reserve": "", "token2_denom": { "cw20": "..." }, "lp_token_supply": "", "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": "" } ``` {% 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": "" } ``` {% endstep %} {% step %} ### Fee {} * Purpose: current fee settings and owner (if set). Request message: ``` { "fee": {} } ``` Response: ``` { "owner": "wasm1..." , "lp_fee_percent": "", "protocol_fee_percent": "", "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": "" } } ``` Response: ``` { "token2_amount": "" } ``` * Price Token2 -> Token1: ``` { "token2_for_token1_price": { "token2_amount": "" } } ``` Response: ``` { "token1_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": , "owner": "wasm1...", "protocol_fee_recipient": "wasm1...", "protocol_fee_percent": "", "lp_fee_percent": "" } ``` 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. --- # 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.axiomeinfo.org/developer-documentation/axiome-trade-contract-api.md?ask= ``` 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.