# GrelfSwap — Hedera DeFi Agent API

> GrelfSwap is a zero-custody DEX aggregator on the Hedera network with a public API built for autonomous AI agents. No API keys required. Supports token swaps, smart orders (limit orders & DCA), real-time pricing, and wallet balance queries. Agents sign and submit all transactions themselves.

## API Documentation
- [SKILL Document (Full API Reference)](https://grelfswap.com/api/public/agent/skill): Complete endpoint documentation, request/response schemas, error handling patterns, and integration guide
- [JavaScript SDK](https://grelfswap.com/api/public/agent/sdk.js): Drop-in helper script with `executeSwap()`, `getQuote()`, `approveAllowance()`, and more
- [OpenAPI 3.0 Specification](https://grelfswap.com/api/public/agent/openapi.json): Machine-readable API spec for tool generation and agent frameworks
- [Tool Schema (OpenAI Function Calling)](https://grelfswap.com/api/public/agent/tools.json): Ready-to-use tool definitions for LangChain, CrewAI, OpenAI Assistants, and custom agent frameworks

## Base URL
- [API Base](https://grelfswap.com/api/public/agent): All endpoints are under this path

## Read-Only Endpoints (No Wallet Required)
- [GET /status](https://grelfswap.com/api/public/agent/status): API status, supported DEXs, endpoint list, and contract addresses
- [GET /quote](https://grelfswap.com/api/public/agent/quote): Get swap quotes with route comparison, price impact, and USD deviation
- [GET /prices](https://grelfswap.com/api/public/agent/prices): USD prices for any Hedera token (SaucerSwap)
- [GET /tokens](https://grelfswap.com/api/public/agent/tokens): Full list of tradeable tokens with metadata

## Wallet Endpoints (Hedera Account Required)
- [POST /swap](https://grelfswap.com/api/public/agent/swap): Execute token swaps with batch mode (HIP-551 atomic transactions)
- [POST /smart-order](https://grelfswap.com/api/public/agent/smart-order): Create limit orders and DCA orders
- [GET /balances](https://grelfswap.com/api/public/agent/balances): Wallet token balances across HBAR, SaucerSwap, and MemeJob
- [POST /associate](https://grelfswap.com/api/public/agent/associate): Associate tokens with wallet
- [POST /approve](https://grelfswap.com/api/public/agent/approve): Grant token allowances to swap contracts

## Key Features
- Zero custody — agents sign everything, platform never holds keys
- Batch mode (HIP-551) — atomic multi-step swaps in one transaction
- Smart Orders — limit orders (4 strategies) and DCA (daily/weekly/monthly)
- Swap pre-simulation — SaucerSwap swaps verified via Mirror Node before returning
- Structured errors with `suggestedAction` for automated agent recovery
- Multi-DEX routing — SaucerSwap V1 + V2 + MemeJob bonding curves
- Agent tracking via optional `X-Agent-ID` header

## Supported Networks
- Hedera Mainnet

## Contracts
- ManualSwaps: `0.0.10233895`
- AutomatedSwaps: `0.0.10234058`
- Saucerswap: `0.0.3045981` 
- Saucerswap: `0.0.6755814` 
- MemeJob: `0.0.7891970`