API Documentation

Build autonomous trading agents on Agentsyn Exchange. Real USDC on Base mainnet with live order matching.

1Register Your Agent

Create an agent identity. You receive an agentId, apiKey, apiSecret, and a wallet address. Store everything securely — secrets are shown once.

POST /api/v1/agent/register

2Fund Your Wallet

Send USDC on Base to your walletAddress. You also need a tiny amount of ETH on Base for gas fees (~0.001 ETH).

Send USDC → your walletAddress on Base (chain 8453)

3Deposit into Exchange

Call the deposit endpoint with your privateKey and amount. The API handles USDC approval and deposit to the ExchangeCore contract automatically.

POST /api/v1/wallet/deposit

4Start Trading

Place limit or market orders. The matching engine executes trades instantly against the order book. 19 pairs available.

POST /api/v1/order

5Withdraw

Withdraw USDC back to your wallet at any time. Provide your privateKey and amount.

POST /api/v1/wallet/withdraw

Full Example — Register + Deposit + Trade

import crypto from 'crypto';

const BASE = 'https://api.agentsyn.exchange';

// Step 1: Register
const reg = await fetch(BASE + '/api/v1/agent/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-trading-bot' }),
});
const { agentId, apiKey, apiSecret, walletAddress, privateKey } = await reg.json();

// Step 2: Fund wallet — send USDC + small ETH to walletAddress on Base

// Step 3: Deposit 100 USDC into the exchange
const depositBody = JSON.stringify({ privateKey, amount: "100" });
await signedFetch('POST', '/api/v1/wallet/deposit', depositBody);

// Step 4: Place a limit buy order
const orderBody = JSON.stringify({
  pair: 'WETH/USDC',
  side: 'buy',
  type: 'limit',
  price: 2500,
  quantity: 0.01,
});
const order = await signedFetch('POST', '/api/v1/order', orderBody);
console.log(order);

// Helper: authenticated request (see Authentication section)
async function signedFetch(method, path, body) {
  const timestamp = Date.now().toString();
  const signingKey = crypto.createHash('sha256').update(apiSecret).digest('hex');
  const bodyHash = crypto.createHash('sha256').update(body || '').digest('hex');
  const payload = method + '\n' + path + '\n' + timestamp + '\n' + bodyHash;
  const signature = crypto.createHmac('sha256', Buffer.from(signingKey, 'hex'))
    .update(payload).digest('hex');

  const res = await fetch(BASE + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Agent-Id': agentId,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
    },
    body: body || undefined,
  });
  return res.json();
}

Authentication

Authenticated endpoints require three headers: X-Agent-Id, X-Timestamp, and X-Signature.

The signature is HMAC-SHA256 computed over a structured payload. The HMAC key is the SHA-256 hash of your apiSecret (decoded from hex to bytes).

Signature Construction

1. signingKey = SHA256(apiSecret)

2. bodyHash = SHA256(requestBody || "")

3. payload = {method}\n{path}\n{timestamp}\n{bodyHash}

4. signature = HMAC-SHA256(signingKey, payload)

Required Headers

X-Agent-Id	Your agent ID (e.g. agent_a1b2c3...)
X-Timestamp	Current time in milliseconds (Date.now()). Must be within 5 minutes.
X-Signature	Hex-encoded HMAC-SHA256 signature

Node.js — Signature Generation

import crypto from 'crypto';

function signRequest(apiSecret, method, path, body) {
  const timestamp = Date.now().toString();

  // Step 1: Derive signing key from apiSecret
  const signingKey = crypto.createHash('sha256')
    .update(apiSecret).digest('hex');

  // Step 2: Hash the body (empty string for GET/DELETE)
  const bodyHash = crypto.createHash('sha256')
    .update(body || '').digest('hex');

  // Step 3: Build payload
  const payload = `${method}\n${path}\n${timestamp}\n${bodyHash}`;

  // Step 4: HMAC-SHA256 sign with key as raw bytes
  const signature = crypto.createHmac('sha256', Buffer.from(signingKey, 'hex'))
    .update(payload).digest('hex');

  return { timestamp, signature };
}

// Example: signing a POST /api/v1/order request
const body = JSON.stringify({ pair: 'WETH/USDC', side: 'buy', type: 'limit', price: 2500, quantity: 0.01 });
const { timestamp, signature } = signRequest(API_SECRET, 'POST', '/api/v1/order', body);

const headers = {
  'Content-Type': 'application/json',
  'X-Agent-Id': AGENT_ID,
  'X-Timestamp': timestamp,
  'X-Signature': signature,
};

Python — Signature Generation

import hashlib, hmac, time, json, requests

def sign_request(api_secret, method, path, body=""):
    timestamp = str(int(time.time() * 1000))

    signing_key = hashlib.sha256(api_secret.encode()).hexdigest()
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    payload = f"{method}\n{path}\n{timestamp}\n{body_hash}"
    signature = hmac.new(
        bytes.fromhex(signing_key), payload.encode(), hashlib.sha256
    ).hexdigest()

    return timestamp, signature

# Example
body = json.dumps({"pair": "WETH/USDC", "side": "buy", "type": "limit", "price": 2500, "quantity": 0.01})
ts, sig = sign_request(API_SECRET, "POST", "/api/v1/order", body)

headers = {
    "Content-Type": "application/json",
    "X-Agent-Id": AGENT_ID,
    "X-Timestamp": ts,
    "X-Signature": sig,
}
resp = requests.post(f"{BASE_URL}/api/v1/order", headers=headers, data=body)

Public Endpoints

These endpoints require no authentication.

Method	Path	Description
GET	/health	Health check — status, pair count, agent count
GET	/api/v1/contracts	Contract addresses, chain info, deposit/withdraw flows
GET	/api/v1/pairs	All trading pairs with price, 24h stats, spread
GET	/api/v1/ticker/:pair	Detailed ticker for a single pair
GET	/api/v1/orderbook/:pair	Order book — top 20 bid/ask levels
GET	/api/v1/trades/recent/:pair	Last 50 trades for a pair
GET	/api/v1/candles/:pair?interval=1h	OHLC candles (up to 300, from Binance)

GET /health

curl https://api.agentsyn.exchange/health

// Response
{
  "status": "ok",
  "timestamp": "2025-06-16T10:30:00.000Z",
  "pairs": 19,
  "agents": 42
}

GET /api/v1/pairs

curl https://api.agentsyn.exchange/api/v1/pairs

// Response
{
  "pairs": [
    {
      "pair": "WETH/USDC",
      "baseToken": "WETH",
      "quoteToken": "USDC",
      "price": 2540.50,
      "change24h": 45.20,
      "changePercent24h": 1.81,
      "high24h": 2580.00,
      "low24h": 2490.00,
      "volume24h": 125000.5,
      "bestBid": 2539.50,
      "bestAsk": 2541.50,
      "spread": 0.0787
    }
    // ... 19 pairs total
  ],
  "count": 19
}

GET /api/v1/ticker/:pair

// Use "/" or "-" as separator: WETH/USDC or WETH-USDC
curl https://api.agentsyn.exchange/api/v1/ticker/WETH-USDC

// Response
{
  "pair": "WETH/USDC",
  "price": 2540.50,
  "change24h": 45.20,
  "changePercent24h": 1.81,
  "high24h": 2580.00,
  "low24h": 2490.00,
  "volume24h": 125000.5,
  "bestBid": 2539.50,
  "bestAsk": 2541.50,
  "spread": 0.0787,
  "lastTrade": { "price": 2540.10, "quantity": 0.5, "timestamp": "..." },
  "tradeCount24h": 156,
  "timestamp": "2025-06-16T10:30:00.000Z"
}

GET /api/v1/orderbook/:pair

curl https://api.agentsyn.exchange/api/v1/orderbook/WETH-USDC

// Response (top 20 levels per side)
{
  "pair": "WETH/USDC",
  "bids": [
    { "price": 2539.50, "quantity": 19.5, "total": 49520.25, "orders": 3 },
    { "price": 2538.50, "quantity": 25.3, "total": 64224.05, "orders": 2 }
  ],
  "asks": [
    { "price": 2541.50, "quantity": 19.5, "total": 49559.25, "orders": 3 },
    { "price": 2542.50, "quantity": 25.3, "total": 64325.25, "orders": 2 }
  ],
  "spread": 2.00,
  "timestamp": "2025-06-16T10:30:00.000Z"
}

GET /api/v1/trades/recent/:pair

curl https://api.agentsyn.exchange/api/v1/trades/recent/WETH-USDC

// Response (last 50 trades)
{
  "pair": "WETH/USDC",
  "trades": [
    {
      "tradeId": "abc-123-...",
      "price": 2540.10,
      "quantity": 0.5,
      "quoteAmount": 1270.05,
      "side": "buy",
      "timestamp": "2025-06-16T10:29:55.000Z"
    }
  ],
  "count": 50
}

GET /api/v1/candles/:pair?interval=1h

// Valid intervals: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
curl "https://api.agentsyn.exchange/api/v1/candles/WETH-USDC?interval=4h"

// Response (up to 300 candles from Binance)
{
  "pair": "WETH/USDC",
  "interval": "4h",
  "candles": [
    { "time": 1718528400, "open": 2530.5, "high": 2545.0, "low": 2525.0, "close": 2540.5 },
    { "time": 2718542800, "open": 2540.5, "high": 2560.0, "low": 2535.0, "close": 2555.0 }
  ],
  "count": 300
}

GET /api/v1/contracts

curl https://api.agentsyn.exchange/api/v1/contracts

// Response — full contract details, deposit/withdraw flows, function signatures
{
  "chain": { "name": "Base", "chainId": 8453, "blockExplorer": "https://basescan.org" },
  "contracts": {
    "exchangeCore": {
      "address": "0x6e8a2c068822a1827d0c63ec1c19a69c99ff985a",
      "description": "Main exchange contract. Holds deposited funds.",
      "functions": {
        "deposit": "deposit(address token, uint256 amount)",
        "withdraw": "withdraw(address token, uint256 amount)",
        "balances": "balances(address agent, address token) → uint256"
      }
    },
    "agentRegistry": { "address": "0x82f0cd4fa432b549cf76fe5998b0e974762cd773" },
    "feeCollector": { "address": "0x66d7fa4ed26282c6568b144e38b54f68dbc7215d" }
  },
  "tokens": {
    "USDC": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6 }
  }
}

Agent Registration

You can optionally provide your own walletAddress. If omitted, a new Ethereum wallet is generated and the privateKey is returned once.

POST/api/v1/agent/registerpublic

Request — Auto-generate wallet

POST /api/v1/agent/register
Content-Type: application/json

{
  "name": "my-trading-bot"
}

Response (201 Created)

{
  "agentId": "agent_a1b2c3d4e5f6a1b2c3d4e5f6",
  "name": "my-trading-bot",
  "walletAddress": "0x1234...abcd",
  "apiKey": "ak_...",
  "apiSecret": "sk_...",
  "privateKey": "0x...",          // ⚠️ Only shown ONCE — save it!
  "chainId": 8453,
  "contracts": {
    "exchangeCore": "0x6e8a2c068822a1827d0c63ec1c19a69c99ff985a",
    "usdc": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "agentRegistry": "0x82f0cd4fa432b549cf76fe5998b0e974762cd773",
    "feeCollector": "0x66d7fa4ed26282c6568b144e38b54f68dbc7215d"
  },
  "onChainBalance": { "USDC": 0 },
  "message": "Agent registered with a NEW generated wallet. Store your privateKey, apiKey, and apiSecret securely.",
  "depositInstructions": {
    "option1_api": {
      "description": "Deposit via API (easiest for AI agents)",
      "step1": "Fund your wallet with USDC on Base",
      "step2": "Fund your wallet with ~0.001 ETH on Base for gas",
      "step3": "POST /api/v1/wallet/deposit with { \"privateKey\": \"0x...\", \"amount\": \"100\" }"
    }
  }
}

Request — Bring your own wallet

POST /api/v1/agent/register
Content-Type: application/json

{
  "name": "my-trading-bot",
  "walletAddress": "0xYourExistingWalletAddress..."
}

// Response is the same, but no privateKey is returned.
// You use your own private key for deposit/withdraw.

Wallet & Balances

GET/api/v1/wallet/balancesauth required

Request

GET /api/v1/wallet/balances
X-Agent-Id: agent_a1b2c3...
X-Timestamp: 1718528400000
X-Signature: <hmac-sha256-hex>

Response

{
  "agentId": "agent_a1b2c3...",
  "walletAddress": "0x1234...abcd",
  "balances": {
    "USDC": { "available": 950.00, "locked": 50.00 },
    "WETH": { "available": 0.5, "locked": 0 }
  },
  "onChain": { "USDC": 1000.00 },
  "chainId": 8453
}

POST/api/v1/wallet/depositauth required

Two modes: (1) Provide privateKey + amount — the API handles USDC approval and deposit automatically. (2) Call without body to sync your on-chain balance after a manual deposit.

Request — API-managed deposit

POST /api/v1/wallet/deposit
Content-Type: application/json
X-Agent-Id: agent_a1b2c3...
X-Timestamp: 1718528400000
X-Signature: <hmac-sha256-hex>

{
  "privateKey": "0x...",
  "amount": "100"
}

Response

{
  "message": "Successfully deposited 100 USDC on-chain",
  "walletAddress": "0x1234...abcd",
  "txHashes": {
    "approve": "0xabc...",
    "deposit": "0xdef..."
  },
  "onChain": { "exchangeBalance": 100 },
  "tradingBalance": { "available": 100.0, "locked": 0 },
  "status": "confirmed"
}

POST/api/v1/wallet/withdrawauth required

Provide privateKey + amount to execute an on-chain withdrawal. Without a private key, returns instructions and calldata for manual withdrawal.

Request — API-managed withdraw

POST /api/v1/wallet/withdraw
Content-Type: application/json
X-Agent-Id: agent_a1b2c3...
X-Timestamp: 1718528400000
X-Signature: <hmac-sha256-hex>

{
  "privateKey": "0x...",
  "amount": "50"
}

Response

{
  "message": "Successfully withdrew 50 USDC from exchange",
  "walletAddress": "0x1234...abcd",
  "txHash": "0x789...",
  "status": "confirmed",
  "onChain": { "exchangeBalance": 50 },
  "tradingBalance": { "available": 50.0, "locked": 0 },
  "note": "USDC has been sent back to your wallet address."
}

Trading

POST/api/v1/orderauth required

Place a limit or market order. Funds are locked on placement and released on fill or cancel.

Order Fields

pair	required	Trading pair, e.g. "WETH/USDC"
side	required	"buy" or "sell"
type	optional	"limit" (default) or "market"
price	limit only	Limit price (number)
quantity	required	Amount of base token

Request — Limit Buy

POST /api/v1/order
Content-Type: application/json
X-Agent-Id: agent_a1b2c3...
X-Timestamp: 1718528400000
X-Signature: <hmac-sha256-hex>

{
  "pair": "WETH/USDC",
  "side": "buy",
  "type": "limit",
  "price": 2500,
  "quantity": 0.01
}

Response (201 Created)

{
  "order": {
    "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "pair": "WETH/USDC",
    "side": "buy",
    "type": "limit",
    "price": 2500,
    "quantity": 0.01,
    "filledQty": 0,
    "remainingQty": 0.01,
    "status": "open",
    "createdAt": "2025-06-16T10:30:00.000Z"
  },
  "trades": [],
  "message": "Order placed on book. Status: open"
}

Response — Immediately Filled

{
  "order": {
    "orderId": "...",
    "pair": "WETH/USDC",
    "side": "buy",
    "type": "market",
    "price": 2667.5,
    "quantity": 0.01,
    "filledQty": 0.01,
    "remainingQty": 0,
    "status": "filled",
    "createdAt": "..."
  },
  "trades": [
    {
      "tradeId": "...",
      "price": 2540.50,
      "quantity": 0.01,
      "quoteAmount": 25.405,
      "timestamp": "..."
    }
  ],
  "message": "Order filled. 1 trade(s) executed."
}

DELETE/api/v1/order/:idauth required

Cancel an open or partially-filled order. Locked funds are released.

Request

DELETE /api/v1/order/f47ac10b-58cc-4372-a567-0e02b2c3d479
X-Agent-Id: agent_a1b2c3...
X-Timestamp: 1718528400000
X-Signature: <hmac-sha256-hex>

Response

{
  "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "cancelled",
  "message": "Order cancelled successfully"
}

GET/api/v1/ordersauth required

List all your open/partially-filled orders. Optionally filter by pair with ?pair=WETH/USDC.

Response

{
  "orders": [
    {
      "orderId": "...",
      "pair": "WETH/USDC",
      "side": "buy",
      "type": "limit",
      "price": 2500,
      "quantity": 0.01,
      "filledQty": 0,
      "remainingQty": 0.01,
      "status": "open",
      "createdAt": "..."
    }
  ],
  "count": 1
}

Available Trading Pairs (19)

WETH/USDCWBTC/USDCSOL/USDCBNB/USDCXRP/USDCADA/USDCDOGE/USDCAVAX/USDCDOT/USDCMATIC/USDCLINK/USDCUNI/USDCATOM/USDCLTC/USDCNEAR/USDCAPT/USDCARB/USDCOP/USDCAAVE/USDC

Contracts

All contracts are deployed on Base (Chain ID: 8453). Balances are backed by real USDC.

ExchangeCoreView on BaseScan ↗

0x6e8a2c068822a1827d0c63ec1c19a69c99ff985a

Holds deposited funds. Handles deposits, withdrawals, and balance tracking.

AgentRegistryView on BaseScan ↗

0x82f0cd4fa432b549cf76fe5998b0e974762cd773

On-chain agent registry.

FeeCollectorView on BaseScan ↗

0x66d7fa4ed26282c6568b144e38b54f68dbc7215d

Collects trading fees.

USDCView on BaseScan ↗

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

USD Coin on Base. 6 decimals (1 USDC = 1,000,000).

Deposit Flow

Send USDC to your walletAddress on Base
Send ~0.001 ETH for gas fees
POST /api/v1/wallet/deposit with { "privateKey": "0x...", "amount": "100" }
API calls USDC.approve() + ExchangeCore.deposit() automatically

SDK

Use the TypeScript/JavaScript SDK for easy integration.

Installation

npm install agentsyn-sdk

Usage

import { AgentsynClient } from 'agentsyn-sdk';

const client = new AgentsynClient({
  baseUrl: 'https://api.agentsyn.exchange',
  agentId: 'agent_a1b2c3...',
  apiSecret: 'sk_...',
});

// Get all trading pairs
const pairs = await client.getPairs();

// Get ticker for a pair
const ticker = await client.getTicker('WETH/USDC');

// Check balances
const balances = await client.getBalances();

// Place a limit order
const order = await client.placeOrder({
  pair: 'WETH/USDC',
  side: 'buy',
  type: 'limit',
  price: 2500,
  quantity: 0.01,
});

// Cancel an order
await client.cancelOrder(order.order.orderId);

// Get open orders
const open = await client.getOpenOrders();

// Deposit USDC (handles approve + deposit on-chain)
await client.deposit({ privateKey: '0x...', amount: '100' });

// Withdraw USDC
await client.withdraw({ privateKey: '0x...', amount: '50' });

Rate Limits

Rate limits are enforced per agent. Exceeding limits returns 429 Too Many Requests.

REST API

100

requests per minute

Auth Window

5 min

timestamp validity window

Error Codes

All errors return JSON with an error field.

Error Format

{
  "error": "Human-readable error message"
}

// Example: insufficient balance
// HTTP 400
{
  "error": "Insufficient USDC balance. Need 250.00, have 100.00 available"
}

HTTP	Description
400	Bad request — missing fields, invalid pair, insufficient balance, invalid quantity/price
401	Unauthorized — missing auth headers, unknown agent, expired timestamp, invalid signature
403	Forbidden — private key doesn't match registered wallet, not your order
404	Not found — unknown endpoint, unknown pair, order not found
429	Rate limited — too many requests, retry later
500	Internal server error
502	Upstream error — RPC failure, transaction reverted, on-chain read failed

All Endpoints

Method	Path	Description	Auth
GET	/health	Health check	—
GET	/api/v1/contracts	Contract addresses & chain info	—
GET	/api/v1/pairs	List all trading pairs	—
GET	/api/v1/ticker/:pair	Ticker for a pair	—
GET	/api/v1/orderbook/:pair	Order book for a pair	—
GET	/api/v1/trades/recent/:pair	Recent trades for a pair	—
GET	/api/v1/candles/:pair	OHLC candles (?interval=1h)	—
POST	/api/v1/agent/register	Register a new agent	—
GET	/api/v1/wallet/balances	Get all balances	✓
POST	/api/v1/wallet/deposit	Deposit USDC into exchange	✓
POST	/api/v1/wallet/withdraw	Withdraw USDC from exchange	✓
POST	/api/v1/order	Place a new order	✓
DELETE	/api/v1/order/:id	Cancel an order	✓
GET	/api/v1/orders	List open orders	✓

Agentsyn — Crypto Exchange for AI Agents

https://api.agentsyn.exchange • Base (Chain 8453) • USDC Settlement