# 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`, `fees` and `max_from_amount` per rate type, and `available_reserve`.
- `POST /api/v1/swaps`: create an order with body `{pair_symbol, rate_type (floating|fixed), from_amount, destination_address, refund_address?}`. Returns `id`, `deposit_address`, the quote fields, and `expires_at`.
- `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.
- Convert whole tokens to base units with the token's `decimals`: ETH 18, USDC 6, BTC 8, XMR 12.
- `failed` means the deposit arrived but the automatic payout could not be sent; the operator refunds it manually; contact support with the swap `id`.