# omenswap

**omenswap is a non-custodial crypto swap service for AI agents and humans.**

omenswap lets autonomous AI agents and regular users swap crypto without custody, accounts, or SDKs.

## Why omenswap for AI agents
- **Native MCP integration** (recommended): a first-class MCP server with tools, a guide resource, and a prompt. Agents get structured `get_info`, `list_pairs`, `get_quote`, `create_swap`, `get_swap_status` instead of scraping HTTP.
- **Truly non-custodial**: the agent controls its own wallet. Call create_swap, then sign+send the deposit from the agent's wallet to the returned address. omenswap pays the destination.
- **Zero friction**: no accounts and no API keys. Works over plain HTTP plus one on-chain transaction.
- **Multi-chain**: ETH, USDC, USDT, BTC, XMR, SOL, TRON and more. Floating and fixed-rate swaps.

## Quick start for agents
1. Use the MCP server (best) or call the public API directly.
2. Discover with list_pairs / get_info.
3. Optionally get_quote to preview a price.
4. create_swap → get deposit_address.
5. Send the exact amount from your wallet to that address on the correct chain.
6. Poll get_swap_status until completed.

Base URL: https://omenswap.com
All API endpoints are under /api/v1. No auth needed for public endpoints (rate limited per IP).

**MCP setup (Claude, Cursor, etc.), recommended**:
```json
{
  "mcpServers": {
    "omenswap": {
      "url": "https://mcp.omenswap.com"
    }
  }
}
```
For a self-hosted deployment, use your own instance URL. A standalone binary is available if you need the stdio transport.

## Links for agents and LLMs
- Full guide: /api.md
- This file: /llms.txt (llmstxt.org convention)
- AGENTS.md: /AGENTS.md
- MCP guide resource inside the server: omenswap://guide

Supported assets (live list always from /tokens and /pairs): ETH, USDC, USDT, BTC, XMR, SOL, TRON across Ethereum, Bitcoin, Monero, Polygon, Tron and Solana.

omenswap never holds keys or funds long-term. Deposit to a unique one-time address; omenswap handles the payout.

## Security model
- The MCP server is a thin, unprivileged client: it never sees private keys, never signs transactions, and never touches the hot wallet or database.
- All sensitive actions (the on-chain deposit) happen in the agent's or user's own wallet.
- Public endpoints are rate-limited (HTTP 429 when exceeded).
- No admin functionality is exposed through the MCP.

## API
- [Full agent guide](https://omenswap.com/api.md): step-by-step swap flow, curl + `cast` examples, MCP setup, errors, and an end-to-end script.
- `GET /api/v1/info`: Ethereum chain id, required confirmations, fees and expiry per rate type, swap status lifecycle. BTC and XMR use their own confirmation depths.
- `GET /api/v1/tokens`: supported assets with `contract_address` (absent for native ETH/BTC/XMR), `decimals`, and `native` flag.
- `GET /api/v1/pairs`: tradeable markets with live `rate`, plus `fees`, `min_from_amount` and `max_from_amount` per rate type, and `available_reserve`. Skip a pair when `price_unavailable` or `payout_unavailable` is set, when `fixed_rate_unavailable` is set and you want a fixed order, or when the reserve or your rate type's `max_from_amount` is `0`.
- `POST /api/v1/swaps`: create an order with body `{pair_symbol, rate_type (floating|fixed), destination_address, refund_address?}` plus exactly one amount field: `from_amount` for `floating`, or `to_amount` for `fixed`. The two are mutually exclusive and sending the wrong one returns `400 INVALID_AMOUNT`. Returns `id`, `deposit_address`, the quote fields, and `expires_at`; on a fixed order the `from_amount` you must deposit is derived and returned. There is no REST quote endpoint, so price from the `rate` in `/pairs` or use the `get_quote` MCP tool.
- `GET /api/v1/swaps/{id}`: order status: `pending` → `awaiting_confirmation` → `deposited` → `completed` (or `expired` / `refunded` / `failed`).

## Notes
- Send your deposit to the exact `deposit_address` returned, on the input asset's chain (an Ethereum address for ETH/USDC, a Bitcoin address for BTC, a Monero address for XMR), before `expires_at`.
- Deposit exactly `from_amount`: `fixed` orders pay the locked quote regardless of amount sent; `floating` orders recompute payout from the amount received. On a fixed order `from_amount` is the derived value in the response, not one you choose.
- Every deposit asset has a minimum of roughly $10 worth (ETH 0.004, BTC 0.0001, XMR 0.05, SOL 0.07, stablecoins 10). The authoritative per-pair value is `min_from_amount` from `/pairs`. It is enforced on the deposit side, so on a fixed order it applies to the derived `from_amount`.
- Convert whole tokens to base units with the token's `decimals`: ETH 18, XMR 12, SOL 9, BTC 8, and 6 for USDC, USDT and their Polygon and Tron variants.
- `failed` means the deposit arrived but the automatic payout could not be sent; the operator refunds it manually; contact support with the swap `id`.