AMM (Swaps) API

On-chain token-to-token swaps via Uniswap V2 on Celo.

▸API ConfigurationNot configured

Price Quote

Get expected output amounts for a swap.

Swap Quote

curl -X GET "http://localhost:8100/api/v1/swap/quote?from=USDT&to=IMC&amountIn=1000000" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "from": "USDT", "to": "IMC", "amountIn": "1000000", "amounts": ["1000000", "1998000"], "amountOut": "1998000" }

Query Parameters:

Param	Type	Description
from	string	Input token symbol (e.g. "USDT")
to	string	Output token symbol (e.g. "IMC")
amountIn	string	Input amount in base units

---

Execute Swap

Swaps an exact amount of input tokens for output tokens. Gas is relayed by the platform.

Execute Swap

curl -X POST "http://localhost:8100/api/v1/swap/tokens" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE" \
  -d '{"tenantSlug": "comet", "userId": 12345, "from": "USDT", "to": "IMC", "amountIn": "1000000"}'

Response200

{ "status": "success", "from": "USDT", "to": "IMC", "amountIn": "1000000", "txHash": "0x...", "chainId": 11142220 }

Request Fields:

Field	Type	Required	Description
tenantSlug	string	No	Tenant (defaults to "comet")
userId	number	Yes	User whose wallet to swap from
from	string	Yes	Input token symbol
to	string	Yes	Output token symbol
amountIn	string	Yes	Input amount in base units

WARNING

The user's wallet must hold at least amountIn of the from token and have approved the router for the swap. The amountOutMin is set to 0 (accepts any output) for testnet simplicity.

---

List Pools

Returns all AMM pool information (pairs and reserves).

List Pools

curl -X GET "http://localhost:8100/api/v1/swap/pools" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN_HERE"

Response200

{ "pools": [{ "token0": "0x3C8E...DDDF", "token1": "0xF150...d5A2", "pair": "0xfE6A...4082", "reserve0": "500000000000", "reserve1": "1000000000000" }], "count": 3 }

---

Full Swap Example

Swap USDT → IMC

# Step 1: Mint USDT to user
curl -X POST http://localhost:8100/api/v1/assets/usdt/mint \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN" \
  -d '{"userId": 123, "amountBase": "10000000", "externalId": "swap-001"}'

# Step 2: Get quote
curl "http://localhost:8100/api/v1/swap/quote?from=USDT&to=IMC&amountIn=10000000" \
  -H "X-Service-Token: YOUR_TOKEN"
# => {"amountOut": "9970000", ...}

# Step 3: Approve router
curl -X POST http://localhost:8100/api/v1/assets/usdt/approve \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN" \
  -d '{"userId": 123, "amountBase": "10000000"}'

# Step 4: Execute swap
curl -X POST http://localhost:8100/api/v1/swap/tokens \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN" \
  -d '{"userId": 123, "from": "USDT", "to": "IMC", "amountIn": "10000000"}'
# => {"status":"success","txHash":"0x...","chainId":11142220}

Swap IMC → USDT

# Step 1: Get quote
curl "http://localhost:8100/api/v1/swap/quote?from=IMC&to=USDT&amountIn=5000000" \
  -H "X-Service-Token: YOUR_TOKEN"

# Step 2: Approve router
curl -X POST http://localhost:8100/api/v1/assets/imc/approve \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN" \
  -d '{"userId": 123, "amountBase": "5000000"}'

# Step 3: Execute swap
curl -X POST http://localhost:8100/api/v1/swap/tokens \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: YOUR_TOKEN" \
  -d '{"userId": 123, "from": "IMC", "to": "USDT", "amountIn": "5000000"}'

---

Supported Pools

Pool	Fee
USDT/USDC	0.3%
USDT/IMC	0.3%
USDC/IMC	0.3%

How It Works

1. User's wallet must hold the input token
2. User approves the Uniswap V2 Router to spend input tokens
3. Engine calls swapExactTokensForTokens() on the Router
4. Router executes the swap on-chain
5. Output tokens arrive in the user's wallet
6. Gas is paid by the platform relayer