Skip to main content

DEX API

REST endpoints for decentralized exchange operations.

Get All Pools​

GET /rp1/dex/v1/pools

Response​

{
  "pools": [
    {
      "id": "1",
      "token_a": {"denom": "urp1", "amount": "1000000000"},
      "token_b": {"denom": "uusdc", "amount": "500000000"},
      "lp_token_denom": "pool1",
      "total_shares": "500000000",
      "swap_fee": "0.003"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "10"
  }
}

Get Pool by ID​

GET /rp1/dex/v1/pool/{pool_id}

Response​

{
  "pool": {
    "id": "1",
    "token_a": {"denom": "urp1", "amount": "1000000000"},
    "token_b": {"denom": "uusdc", "amount": "500000000"},
    "lp_token_denom": "pool1",
    "total_shares": "500000000",
    "swap_fee": "0.003"
  }
}

Get Swap Quote​

GET /rp1/dex/v1/quote

Query Parameters​

ParameterTypeDescription
pool_idstringPool identifier
token_instringInput token denom
amount_instringInput amount

Response​

{
  "amount_out": "498500000",
  "spot_price_before": "0.5",
  "spot_price_after": "0.501",
  "price_impact": "0.002",
  "fee": "1500000"
}

Get LP Position​

GET /rp1/dex/v1/position/{address}/{pool_id}

Response​

{
  "position": {
    "owner": "rp1owner...",
    "pool_id": "1",
    "shares": "100000000",
    "token_a_value": "200000000",
    "token_b_value": "100000000"
  }
}

DEX Module Parameters​

GET /rp1/dex/v1/params

Response​

{
  "params": {
    "default_swap_fee": "0.003",
    "protocol_fee": "0.0005",
    "min_liquidity": "1000000"
  }
}

Transaction Messages​

Create Pool​

{
  "@type": "/rp1.dex.v1.MsgCreatePool",
  "sender": "rp1creator...",
  "token_a": {"denom": "urp1", "amount": "1000000000"},
  "token_b": {"denom": "uusdc", "amount": "500000000"},
  "swap_fee": "0.003"
}

Add Liquidity​

{
  "@type": "/rp1.dex.v1.MsgAddLiquidity",
  "sender": "rp1provider...",
  "pool_id": "1",
  "token_a_amount": "100000000",
  "token_b_amount": "50000000",
  "min_shares": "45000000"
}

Remove Liquidity​

{
  "@type": "/rp1.dex.v1.MsgRemoveLiquidity",
  "sender": "rp1provider...",
  "pool_id": "1",
  "shares": "50000000",
  "min_token_a": "90000000",
  "min_token_b": "45000000"
}

Swap​

{
  "@type": "/rp1.dex.v1.MsgSwap",
  "sender": "rp1trader...",
  "pool_id": "1",
  "token_in": {"denom": "urp1", "amount": "1000000"},
  "min_token_out": "490000"
}

Shielded Swap​

{
  "@type": "/rp1.dex.v1.MsgShieldedSwap",
  "sender": "rp1trader...",
  "pool_id": "1",
  "proof": "base64_encoded_proof",
  "encrypted_amounts": "base64_encrypted",
  "nullifiers": ["null1...", "null2..."],
  "new_commitments": ["comm1...", "comm2..."]
}

Events​

EventAttributes
pool_createdpool_id, creator, token_a, token_b
liquidity_addedpool_id, provider, shares
liquidity_removedpool_id, provider, shares
swappool_id, sender, token_in, token_out
shielded_swappool_id, nullifier

TypeScript Example​

import { DEXModule } from '@rp1/sdk';

const dex = new DEXModule(client);

// Get all pools
const pools = await dex.getPools();
pools.forEach(p => {
  console.log(`Pool ${p.id}: ${p.tokenA.denom}/${p.tokenB.denom}`);
});

// Get swap quote
const quote = await dex.getQuote({
  poolId: '1',
  tokenIn: 'urp1',
  amountIn: '1000000',
});
console.log(`You will receive: ${quote.amountOut}`);
console.log(`Price impact: ${quote.priceImpact}%`);

// Execute swap
const swapTx = await dex.swap(wallet, {
  poolId: '1',
  tokenIn: { denom: 'urp1', amount: '1000000' },
  minTokenOut: quote.amountOut * 0.99, // 1% slippage
});

// Add liquidity
const addLiqTx = await dex.addLiquidity(wallet, {
  poolId: '1',
  tokenAAmount: '100000000',
  tokenBAmount: '50000000',
  minShares: '45000000',
});

// Shielded swap (private)
const shieldedTx = await dex.shieldedSwap(wallet, {
  poolId: '1',
  tokenIn: 'urp1',
  amountIn: '1000000',
});

Price Calculation​

AMM uses constant product formula:

x * y = k

amount_out = (y * amount_in) / (x + amount_in)

With fees:

amount_in_after_fee = amount_in * (1 - swap_fee)
amount_out = (y * amount_in_after_fee) / (x + amount_in_after_fee)

Next Steps​