LLM Integration

# Naos Trade API — Integration Guide

> Quick reference for developers integrating the Naos Trade API.
> Base URL: https://api.naos.trade
> Docs: https://doc.naos.trade

---

## API Structure

Base URL: https://api.naos.trade
Auth: Authorization: Bearer <API_KEY>
Request an API key at https://naos.trade

### Trading Flow

1. Quote — GET /api/v2/quote → returns unsigned transaction + price data
2. Sign — client-side with ethers.js/viem (EVM) or @solana/web3.js (Solana)
3. Execute — POST /api/v2/execute → broadcasts signed transaction, returns result

### Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| /api/v2/quote | GET | Unsigned swap tx + price quote |
| /api/v2/execute | POST | Broadcast signed tx |
| /api/v1/token-info | GET | Token metadata + pool + taxes + audit |
| /api/v1/token-audit | GET | Security audit |
| /api/v2/value | GET | Fast price estimate (no tx) |
| /api/v1/priority | GET | Gas fee estimates per priority level |
| /api/v1/chains | GET | Supported chains list |
| /api/v1/balance | GET | Token balance across chains |
| /api/health | GET | Health check (no auth) |

---

## Supported Chains (15)

EVM: BASE, ETH, BSC, ARB, AVAX, ABS, HYPE, INK, STORY, XLAYER, PLASMA, UNI, MONAD, MEGAETH
Non-EVM: SOL (Solana)

Native token address (all chains): 0x0000000000000000000000000000000000000000

---

## Endpoint Reference

### GET /api/v2/quote

Parameters:
- tokenIn (required): input token address. Use 0x0000000000000000000000000000000000000000 for native
- tokenOut (required): output token address. Use 0x0000000000000000000000000000000000000000 for native
- amount (required): amount of tokenIn in smallest unit (wei). Supports percentage: "50%"
- slippage (required): slippage in basis points. 500 = 5%
- trader (optional but recommended): wallet address that will sign
- chain (required): network identifier (BASE, ETH, BSC, etc.)
- priority (optional): gas priority — LOW, MEDIUM, HIGH, INSTANT
- simulation (optional): pre-flight simulation. Default false
- integrator (optional): fee recipient wallet address
- fee (optional): integrator fee in bps (0 or 10-500)

Response:
- success: boolean
- stats.amountOut: expected output in raw units
- stats.amountOutMin: minimum output after slippage
- stats.valueAmountInUsd: trade value in USD
- stats.txCostUsd: estimated gas cost in USD
- transaction.trade: unsigned trade transaction (hex for EVM, base64 for SOL)
- transaction.approve: unsigned approval transaction (empty string if not needed)
- transaction.extra: unsigned extra transaction (fee tx for launchpad tokens)
- transaction.quoteId: unique ID, required for execute

### POST /api/v2/execute

Body (JSON):
- trade (required): signed trade transaction
- chain (required): network
- mev (required): MEV protection (effective on ETH, BSC)
- simulation (required): pre-flight simulation
- quoteId (required): from quote response
- approve (optional): signed approval transaction
- extra (optional): signed extra transaction
- reward (optional): address for MEV kickback rewards

Response:
- success: boolean
- status: SUCCESS or FAILED
- txRes.txHash: on-chain transaction hash
- txRes.explorerUrl: block explorer link
- txRes.spent: amount spent (human-readable)
- txRes.received: amount received (human-readable)
- parsedError: machine-readable error code

### GET /api/v1/token-info

Parameters:
- token (required): token address
- chain (optional): auto-detected if omitted
- audit (optional): "false" to skip audit

### GET /api/v1/balance

Parameters:
- wallet (required): wallet address
- token (required): token address (use zero address for native)
- chains (required): JSON array of chains, e.g. ["BASE","ETH"]

### GET /api/v2/value

Parameters:
- tokenIn (required): input token address (use 0x0000000000000000000000000000000000000000 for native)
- tokenOut (required): output token address (use 0x0000000000000000000000000000000000000000 for native)
- trader (optional): wallet address (used to fetch tokenIn balance when amount is omitted)
- amount (optional): amount of tokenIn to trade (defaults to trader's full balance if omitted)
- chain (optional): auto-detected if omitted

### GET /api/v1/priority

Parameters:
- network (required): chain identifier

### GET /api/v1/token-audit

Parameters:
- token (required): token address
- chain (optional): auto-detected if omitted

### GET /api/v1/chains

No parameters required.

---

## Chain-Specific Behaviors

### Transaction Format
- EVM: hex string (0x...), sign with ethers.js or viem
- Solana: base64-encoded VersionedTransaction, sign with @solana/web3.js

### Transactions to Sign
1. trade — the main swap transaction (always present when success is true)
2. approve — token approval (present when selling a token that needs allowance)
3. extra — additional transaction (fee tx for launchpad tokens, permit2 for strategy tokens)

---

## Fee System

Two layers on every swap:
1. Base protocol fee: fixed 10 BPS (0.1%)
2. Variable fee: driven by fee param (0 or 10-500 BPS), split 80% integrator / 20% protocol

---

## Quick Start (EVM)

import { ethers } from 'ethers'

const API = 'https://api.naos.trade'
const headers = { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }
const NATIVE = '0x0000000000000000000000000000000000000000'

// 1. Get quote
const quote = await fetch(`${API}/api/v2/quote?tokenIn=${NATIVE}&tokenOut=0xTOKEN&amount=10000000000000000&slippage=500&trader=0xWALLET&chain=BASE`, { headers }).then(r => r.json())

// 2. Sign
const wallet = new ethers.Wallet(PRIVATE_KEY)
const signedTrade = await wallet.signTransaction(ethers.Transaction.from(quote.transaction.trade))
const signedApprove = quote.transaction.approve ? await wallet.signTransaction(ethers.Transaction.from(quote.transaction.approve)) : undefined

// 3. Execute
const result = await fetch(`${API}/api/v2/execute`, {
  method: 'POST', headers,
  body: JSON.stringify({ trade: signedTrade, chain: 'BASE', mev: false, simulation: false, quoteId: quote.transaction.quoteId, approve: signedApprove })
}).then(r => r.json())

## Important Rules

- Amount must be in smallest unit (wei for EVM, lamports for SOL)
- Quotes expire in ~30 seconds
- Always check the success field
- Always sign and send approve if present
- Always sign and send extra if present
- Slippage is in basis points: 100 = 1%, 500 = 5%