1  # ADnet REST API Reference
  2  
  3  This document provides a complete reference for the ADnet REST API, covering both ALPHA and DELTA chain endpoints.
  4  
  5  ## Base URLs
  6  
  7  | Environment | ALPHA Chain | DELTA Chain |
  8  |-------------|-------------|-------------|
  9  | Devnet (Docker) | `http://localhost:3030` | `http://localhost:4030` |
 10  | Local Development | `http://localhost:3030` | `http://localhost:4030` |
 11  
 12  ## Authentication
 13  
 14  Currently, the API does not require authentication for read operations. Write operations (trading, deposits, withdrawals) require a valid signature in the request body.
 15  
 16  ## Common Response Format
 17  
 18  All endpoints return JSON responses with the following structure:
 19  
 20  **Success Response:**
 21  ```json
 22  {
 23    "success": true,
 24    "data": { ... }
 25  }
 26  ```
 27  
 28  **Error Response:**
 29  ```json
 30  {
 31    "success": false,
 32    "error": {
 33      "code": "ERROR_CODE",
 34      "message": "Human-readable error message"
 35    }
 36  }
 37  ```
 38  
 39  ## Error Codes
 40  
 41  | Code | Description |
 42  |------|-------------|
 43  | `INVALID_REQUEST` | Malformed request or missing required fields |
 44  | `INVALID_SIGNATURE` | Transaction signature verification failed |
 45  | `INSUFFICIENT_BALANCE` | Not enough balance for the operation |
 46  | `ORDER_NOT_FOUND` | The specified order does not exist |
 47  | `ORDER_TOO_SMALL` | Order size below minimum (100 units) |
 48  | `TOO_MANY_ORDERS` | Exceeded maximum orders per user (20) |
 49  | `INSUFFICIENT_LIQUIDITY` | Not enough liquidity to fill market order |
 50  | `PAIR_NOT_SUPPORTED` | Trading pair is not available |
 51  | `BRIDGE_HALTED` | Bridge operations temporarily suspended |
 52  | `INTERNAL_ERROR` | Unexpected server error |
 53  
 54  ---
 55  
 56  ## System Endpoints
 57  
 58  ### GET /health
 59  
 60  Health check endpoint for monitoring.
 61  
 62  **Response:**
 63  ```json
 64  {
 65    "status": "healthy",
 66    "timestamp": 1703548800
 67  }
 68  ```
 69  
 70  ### GET /status
 71  
 72  Get current node status.
 73  
 74  **Response:**
 75  ```json
 76  {
 77    "node_id": "validator-0",
 78    "version": "0.1.0",
 79    "block_height": 12345,
 80    "peer_count": 3,
 81    "is_syncing": false,
 82    "uptime_seconds": 3600
 83  }
 84  ```
 85  
 86  ### GET /info
 87  
 88  Get node and network information.
 89  
 90  **Response:**
 91  ```json
 92  {
 93    "network": "devnet",
 94    "chain_id": "delta-devnet",
 95    "version": "0.1.0",
 96    "genesis_hash": "0x...",
 97    "supported_pairs": ["DX/AX"]
 98  }
 99  ```
100  
101  ---
102  
103  ## Block Endpoints
104  
105  ### GET /block/height
106  
107  Get the current block height.
108  
109  **Response:**
110  ```json
111  {
112    "height": 12345
113  }
114  ```
115  
116  ### GET /block/latest
117  
118  Get the latest block.
119  
120  **Response:**
121  ```json
122  {
123    "height": 12345,
124    "hash": "0x...",
125    "previous_hash": "0x...",
126    "timestamp": 1703548800,
127    "transaction_count": 5,
128    "validator": "validator-0"
129  }
130  ```
131  
132  ---
133  
134  ## Trading Endpoints
135  
136  ### GET /trading/pairs
137  
138  Get list of available trading pairs.
139  
140  **Response:**
141  ```json
142  {
143    "pairs": [
144      {
145        "symbol": "DX/AX",
146        "base": "DX",
147        "quote": "AX",
148        "min_order_size": 100,
149        "tick_size": 1,
150        "status": "active"
151      }
152    ]
153  }
154  ```
155  
156  ### GET /orderbook/{pair}
157  
158  Get the order book for a trading pair.
159  
160  **Path Parameters:**
161  - `pair` - Trading pair symbol (e.g., `DX-AX`)
162  
163  **Query Parameters:**
164  - `depth` (optional) - Number of price levels (default: 10, max: 100)
165  
166  **Response:**
167  ```json
168  {
169    "pair": "DX/AX",
170    "bids": [
171      { "price": 990, "quantity": 1000, "order_count": 3 },
172      { "price": 985, "quantity": 500, "order_count": 1 }
173    ],
174    "asks": [
175      { "price": 1010, "quantity": 800, "order_count": 2 },
176      { "price": 1015, "quantity": 1200, "order_count": 4 }
177    ],
178    "best_bid": 990,
179    "best_ask": 1010,
180    "spread": 20,
181    "timestamp": 1703548800
182  }
183  ```
184  
185  ### POST /orders/limit
186  
187  Place a limit order.
188  
189  **Request Body:**
190  ```json
191  {
192    "pair": "DX/AX",
193    "side": "buy",
194    "price": 1000,
195    "quantity": 500,
196    "time_in_force": "GTC",
197    "signature": "0x..."
198  }
199  ```
200  
201  **Fields:**
202  - `pair` - Trading pair symbol
203  - `side` - `buy` or `sell`
204  - `price` - Limit price in quote currency units
205  - `quantity` - Order quantity in base currency units
206  - `time_in_force` - `GTC` (Good Till Cancelled), `IOC` (Immediate or Cancel), `FOK` (Fill or Kill)
207  - `signature` - Ed25519 signature of the order
208  
209  **Response:**
210  ```json
211  {
212    "order_id": "0x...",
213    "status": "open",
214    "filled_quantity": 0,
215    "remaining_quantity": 500,
216    "created_at": 1703548800
217  }
218  ```
219  
220  ### POST /orders/market
221  
222  Place a market order.
223  
224  **Request Body:**
225  ```json
226  {
227    "pair": "DX/AX",
228    "side": "buy",
229    "quantity": 500,
230    "signature": "0x..."
231  }
232  ```
233  
234  **Response:**
235  ```json
236  {
237    "order_id": "0x...",
238    "status": "filled",
239    "filled_quantity": 500,
240    "average_price": 1005,
241    "trades": [
242      { "price": 1000, "quantity": 300 },
243      { "price": 1010, "quantity": 200 }
244    ]
245  }
246  ```
247  
248  ### DELETE /orders/{id}
249  
250  Cancel an open order.
251  
252  **Path Parameters:**
253  - `id` - Order ID to cancel
254  
255  **Request Body:**
256  ```json
257  {
258    "signature": "0x..."
259  }
260  ```
261  
262  **Response:**
263  ```json
264  {
265    "order_id": "0x...",
266    "status": "cancelled",
267    "remaining_quantity": 300
268  }
269  ```
270  
271  ### GET /orders
272  
273  List user's open orders.
274  
275  **Query Parameters:**
276  - `address` - User's address
277  - `pair` (optional) - Filter by trading pair
278  - `limit` (optional) - Max results (default: 50)
279  
280  **Response:**
281  ```json
282  {
283    "orders": [
284      {
285        "order_id": "0x...",
286        "pair": "DX/AX",
287        "side": "buy",
288        "price": 1000,
289        "quantity": 500,
290        "filled_quantity": 200,
291        "status": "partially_filled",
292        "created_at": 1703548800
293      }
294    ],
295    "total": 1
296  }
297  ```
298  
299  ### GET /trades/{pair}
300  
301  Get recent trades for a trading pair.
302  
303  **Path Parameters:**
304  - `pair` - Trading pair symbol
305  
306  **Query Parameters:**
307  - `limit` (optional) - Max results (default: 50, max: 500)
308  
309  **Response:**
310  ```json
311  {
312    "trades": [
313      {
314        "trade_id": "0x...",
315        "pair": "DX/AX",
316        "price": 1005,
317        "quantity": 100,
318        "side": "buy",
319        "timestamp": 1703548800,
320        "maker_fee": 25,
321        "taker_fee": 75
322      }
323    ]
324  }
325  ```
326  
327  ---
328  
329  ## Balance Endpoints
330  
331  ### GET /balance/{address}
332  
333  Get account balance.
334  
335  **Path Parameters:**
336  - `address` - Account address (ax1... format)
337  
338  **Response:**
339  ```json
340  {
341    "address": "ax1...",
342    "balances": {
343      "DX": 10000,
344      "AX": 5000
345    },
346    "locked": {
347      "DX": 500,
348      "AX": 0
349    }
350  }
351  ```
352  
353  ---
354  
355  ## Bridge Endpoints
356  
357  ### GET /bridge/status
358  
359  Get bridge status and statistics.
360  
361  **Response:**
362  ```json
363  {
364    "status": "active",
365    "alpha_block_height": 50000,
366    "delta_block_height": 12345,
367    "pending_deposits": 3,
368    "pending_withdrawals": 1,
369    "last_attestation_height": 49990,
370    "total_locked_alpha": 1000000,
371    "total_minted_delta": 1000000
372  }
373  ```
374  
375  ### POST /bridge/deposit
376  
377  Initiate a deposit from ALPHA to DELTA.
378  
379  **Request Body:**
380  ```json
381  {
382    "amount": 1000,
383    "alpha_address": "ax1...",
384    "delta_address": "dx1...",
385    "proof": "0x...",
386    "signature": "0x..."
387  }
388  ```
389  
390  **Response:**
391  ```json
392  {
393    "deposit_id": "0x...",
394    "status": "pending",
395    "expected_confirmation_blocks": 6
396  }
397  ```
398  
399  ### POST /bridge/withdraw
400  
401  Request a withdrawal from DELTA to ALPHA.
402  
403  **Request Body:**
404  ```json
405  {
406    "amount": 500,
407    "delta_address": "dx1...",
408    "alpha_address": "ax1...",
409    "signature": "0x..."
410  }
411  ```
412  
413  **Response:**
414  ```json
415  {
416    "withdrawal_id": "0x...",
417    "status": "pending",
418    "expected_confirmation_blocks": 10
419  }
420  ```
421  
422  ---
423  
424  ## ALPHA Chain Endpoints
425  
426  These endpoints are available on the ALPHA REST API (port 3030).
427  
428  ### GET /alpha/status
429  
430  Get ALPHA chain status.
431  
432  **Response:**
433  ```json
434  {
435    "chain": "alpha",
436    "block_height": 50000,
437    "finalized_height": 49997,
438    "peer_count": 5,
439    "is_syncing": false
440  }
441  ```
442  
443  ### GET /alpha/health
444  
445  ALPHA chain health check.
446  
447  **Response:**
448  ```json
449  {
450    "status": "healthy"
451  }
452  ```
453  
454  ### GET /alpha/pool
455  
456  Get transaction pool status.
457  
458  **Response:**
459  ```json
460  {
461    "pending_transactions": 15,
462    "pool_size_bytes": 45000
463  }
464  ```
465  
466  ### GET /alpha/attestation/latest
467  
468  Get the latest cross-chain attestation.
469  
470  **Response:**
471  ```json
472  {
473    "block_height": 49990,
474    "state_root": "0x...",
475    "timestamp": 1703548790,
476    "signature_count": 28,
477    "threshold_met": true
478  }
479  ```
480  
481  ---
482  
483  ## Faucet Endpoint (Devnet Only)
484  
485  ### POST /faucet
486  
487  Request test tokens (devnet only).
488  
489  **Request Body:**
490  ```json
491  {
492    "address": "ax1...",
493    "amount": 10000
494  }
495  ```
496  
497  **Response:**
498  ```json
499  {
500    "success": true,
501    "amount": 10000,
502    "transaction_id": "0x..."
503  }
504  ```
505  
506  ---
507  
508  ## WebSocket API
509  
510  For real-time updates, connect to the WebSocket endpoint:
511  
512  ```
513  ws://localhost:4030/ws
514  ```
515  
516  ### Subscription Messages
517  
518  **Subscribe to order book updates:**
519  ```json
520  {
521    "type": "subscribe",
522    "channel": "orderbook",
523    "pair": "DX/AX"
524  }
525  ```
526  
527  **Subscribe to trades:**
528  ```json
529  {
530    "type": "subscribe",
531    "channel": "trades",
532    "pair": "DX/AX"
533  }
534  ```
535  
536  **Subscribe to user orders:**
537  ```json
538  {
539    "type": "subscribe",
540    "channel": "orders",
541    "address": "ax1..."
542  }
543  ```
544  
545  ### Update Messages
546  
547  **Order book update:**
548  ```json
549  {
550    "type": "orderbook_update",
551    "pair": "DX/AX",
552    "bids": [...],
553    "asks": [...],
554    "timestamp": 1703548800
555  }
556  ```
557  
558  **Trade update:**
559  ```json
560  {
561    "type": "trade",
562    "pair": "DX/AX",
563    "price": 1005,
564    "quantity": 100,
565    "side": "buy",
566    "timestamp": 1703548800
567  }
568  ```
569  
570  ---
571  
572  ## Rate Limits
573  
574  | Endpoint Type | Limit |
575  |---------------|-------|
576  | Read (GET) | 100 requests/minute |
577  | Write (POST/DELETE) | 20 requests/minute |
578  | WebSocket | 10 subscriptions per connection |
579  
580  ---
581  
582  ## SDK Examples
583  
584  ### JavaScript/TypeScript
585  
586  ```typescript
587  // Using fetch
588  const getOrderBook = async (pair: string) => {
589    const response = await fetch(`http://localhost:4030/orderbook/${pair}`);
590    return response.json();
591  };
592  
593  // Place a limit order
594  const placeLimitOrder = async (order: LimitOrder) => {
595    const response = await fetch('http://localhost:4030/orders/limit', {
596      method: 'POST',
597      headers: { 'Content-Type': 'application/json' },
598      body: JSON.stringify(order),
599    });
600    return response.json();
601  };
602  ```
603  
604  ### Python
605  
606  ```python
607  import requests
608  
609  # Get order book
610  def get_orderbook(pair: str) -> dict:
611      response = requests.get(f"http://localhost:4030/orderbook/{pair}")
612      return response.json()
613  
614  # Place a limit order
615  def place_limit_order(order: dict) -> dict:
616      response = requests.post(
617          "http://localhost:4030/orders/limit",
618          json=order
619      )
620      return response.json()
621  ```
622  
623  ### Rust
624  
625  ```rust
626  use reqwest::Client;
627  
628  async fn get_orderbook(client: &Client, pair: &str) -> Result<OrderBook, Error> {
629      let url = format!("http://localhost:4030/orderbook/{}", pair);
630      let response = client.get(&url).send().await?;
631      response.json().await
632  }
633  ```
634  
635  ---
636  
637  ## Changelog
638  
639  | Version | Date | Changes |
640  |---------|------|---------|
641  | 0.1.0 | 2025-12-25 | Initial API release |