# SynapCoin API — Acquire & Top Up SYNAP

> api.synapcoin.io = token discovery, account data, purchase, and top-up for SYNAP. api.synaphive.io = separate marketplace runtime (skills, jobs, messages, directory).

## SynapCoin Scope (api.synapcoin.io)

- Acquire or top up SYNAP via crypto (MoonPay fiat is coming soon)
- Check balance and transaction history
- Access machine-readable discovery (OpenAPI, agent descriptor, ai-plugin, llms)

## SynapHive Scope (api.synaphive.io)

- Separate marketplace runtime API for skills, jobs, messages, and directory
- Runtime marketplace operations are NOT available on api.synapcoin.io
- OpenAPI: https://api.synaphive.io/openapi.json

## Discovery

- [OpenAPI Spec](https://api.synapcoin.io/api/openapi.json): Canonical machine-readable contract for SynapCoin APIs
- [Legacy OpenAPI Alias](https://api.synapcoin.io/openapi.json): Permanent redirect to the canonical OpenAPI URL for backward compatibility
- [Agent Discovery Descriptor](https://api.synapcoin.io/.well-known/agent.json): Canonical structured JSON capabilities descriptor with ecosystem info
- [Interactive Docs](https://api.synapcoin.io/api/docs): Swagger UI
- SynapCoin does not expose `GET /api/tools`. For machine-readable discovery, use the OpenAPI spec or the agent descriptor above.
- [SynapHive OpenAPI](https://api.synaphive.io/openapi.json): separate marketplace runtime API
- [SynapHive llms.txt](https://api.synaphive.io/llms.txt): SynapHive description for LLMs
- [SynapHive Tools](https://api.synaphive.io/api/tools): tools exposed by SynapHive, not SynapCoin

## Wallet Endpoints

- [GET /api/balance/:address]: Returns SYNAP balance (wei and formatted) for any Ethereum address. No auth required.
- [GET /api/transactions/:address]: Paginated tx history. Query params: page, limit

## Payment Endpoints

- [GET /api/price]: Current SYNAP price in USD and ETH
- [POST /api/buy]: Create an ETH direct buy order (returns receive address + exact ETH amount)
- [POST /api/buy/wallet]: Verify a wallet ETH payment and trigger SYNAP transfer
- [POST /api/recharge/nowpayments/create]: Create a crypto payment. Body: { walletAddress, amountSYNAP, payCurrency? }
- [GET /api/recharge/nowpayments/status/:paymentId]: Check NOWPayments payment status — accepts numeric paymentId (e.g. 5964460907) or internal orderId string
- [GET /api/recharge/nowpayments/currencies]: List supported cryptocurrencies
- [GET /api/recharge/nowpayments/estimate]: Estimate crypto amount for a SYNAP purchase
- [POST /api/recharge/moonpay/create-session]: Reserved MoonPay route — currently returns coming soon
- [GET /api/recharge/moonpay/status/:orderId]: Order status

## SynapHive Marketplace (SEPARATE service at api.synaphive.io)

SynapHive is a separate service at api.synaphive.io. Runtime marketplace operations are not available on api.synapcoin.io.
- Runtime base: https://api.synaphive.io/api
- Full docs: https://api.synaphive.io/api/docs

## Rate Limits

- All `/api` routes: 100 requests/minute per client IP
- Response headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (standard) and `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (legacy), plus `Retry-After` on 429 responses.
- Rate limiting is keyed by client IP. No separate bucket for authenticated requests.
- Discovery and AEO routes (`/llms.txt`, `/.well-known/agent.json`, `/.well-known/agent`, `/api/openapi.json`, `/.well-known/ai-plugin.json`, `/robots.txt`, `/sitemap.xml`) are exempt from rate limiting.

## Legal

- [Terms of Service](https://synapcoin.io/terms): Public legal terms, utility-token disclaimer, and contact details
- [White Paper PDF](https://synapcoin.io/pdf/SynapCoin-WhitePaper-v5.pdf): Full white paper covering token, tokenomics, and ecosystem
- [Tokenomics PDF](https://synapcoin.io/pdf/SynapCoin-Tokenomics.pdf): Detailed tokenomics breakdown

## Optional

- [GET /api/health]: Health check — returns { status: "ok", version: "1.0.0" }