Skip to content

quickstart.mdx

Latest commit

 

History

History
109 lines (84 loc) · 3.26 KB

quickstart.mdx

File metadata and controls

109 lines (84 loc) · 3.26 KB
Raw
title Quickstart
description Read the futures orderbook and submit your first signed order

Use this sequence to integrate against Numo's orderbook for physically delivered FX futures.

1. Discover supported markets

Query markets-service first so you know which instruments are enabled in the matcher.

curl "$MARKETS_SERVICE_URL/v1/markets"

For the deliverable cNGN future, look for:

  • market = "USDCcNGN-APR30-2026"
  • contract_type = "deliverable_fx_future"
  • settlement_type = "physical_delivery"
  • asset_address and sub_id

2. Read the book and recent trades

Once you have the market symbol or the (asset_address, sub_id) pair, fetch the current orderbook and recent prints.

curl "$MARKETS_SERVICE_URL/v1/book?symbol=USDCcNGN-APR30-2026"
curl "$MARKETS_SERVICE_URL/v1/trades?symbol=USDCcNGN-APR30-2026&limit=50"

markets-service is the public read surface for:

  • market metadata
  • top-of-book bids and asks
  • recent trades and 24h stats
  • order submission and cancellation

3. Submit a signed order

Orders are posted to markets-service, but the request must already contain a signed action payload that matches the contracts.

curl -X POST "$MARKETS_SERVICE_URL/v1/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "future-order-1",
    "owner_address": "0xOWNER",
    "signer_address": "0xSIGNER",
    "subaccount_id": "10",
    "recipient_id": "10",
    "nonce": "1",
    "side": "buy",
    "asset_address": "0xFUTURE_ASSET",
    "sub_id": "1777507200",
    "desired_amount": "100000000000000000",
    "limit_price": "1605000000000000000000",
    "worst_fee": "0",
    "expiry": 1893456000,
    "action_json": {
      "subaccount_id": "10",
      "nonce": "1",
      "module": "0xTRADE_MODULE",
      "data": "0x...",
      "expiry": "1893456000",
      "owner": "0xOWNER",
      "signer": "0xSIGNER"
    },
    "signature": "0x..."
  }'

markets-service rejects the order unless:

  • the instrument is enabled
  • action_json.subaccount_id matches subaccount_id
  • action_json.nonce matches nonce
  • action_json.owner matches owner_address
  • action_json.signer matches signer_address

4. Let the executor clear crossed orders

The matching loop in markets-service identifies crossed orders and emits a payload to execution-service.

execution-service then:

  • validates the match payload shape
  • ABI-encodes TradeModule.OrderData
  • simulates Matching.verifyAndMatch(...)
  • submits the transaction to the onchain matching contracts

5. Understand where risk and settlement live

execution-contracts owns the trusted backend execution path. risk-core owns the margin system, subaccounts, cash settlement, and liquidation rules.

For the USDCcNGN-APR30-2026 future:

  • settlement type is physical delivery
  • longs pay cNGN and receive fixed USDC notional at expiry
  • shorts pay fixed USDC notional and receive cNGN
Follow the full path across markets-service, execution-service, execution-contracts, and risk-core. Review the public orderbook, trades, and order-entry surface.