HX Africa Docs

Introduction

HX Africa is a real-estate exchange where landmark African properties are tokenized into fungible shares and traded against the Nigerian Naira (NGN) on an institutional-grade order book — the same market structure a top crypto exchange uses, applied to bricks and mortar.

A property only becomes tradeable after a controlled onboarding process: an admin creates the listing and an independent custodian verifies the underlying asset, legal title, valuation and custody arrangements before a single token is minted. Once approved, the market opens and price is discovered continuously on the order book.

System architecture

HX Africa separates the control plane (listing, verification, custody) from the trading plane (matching, market data, settlement). The two meet only at one gate: a market cannot open until its listing is Live.

The matching engine is deliberately single-threaded and deterministic: all book mutations are serialised through one logical sequence so ordering is reproducible and auditable. Everything time-based (candles, 24h stats) lives in a separate market-data layer.

Core concepts

• Listing — the record of a property being onboarded, moving through a defined state machine before it can trade.
• Market — a tradeable, live listing identified by a symbol such as EKO/NGN (base token / quote asset).
• Token — one fungible share of a property, backed 1:1 by a share in its SPV. Quantities are whole tokens.
• Price — quoted in NGN. On the wire, prices are integer kobo (a token worth ₦12.50 has price 1250), so money math is exact.
• Maker / Taker — a maker rests liquidity on the book; a taker crosses the spread to consume it.

Roles & responsibilities

Onboarding a property is a separation-of-duties process. No single party can both create and approve a listing.

An independent Auditor periodically reconciles minted tokens against SPV shares and reviews valuations.

Listing lifecycle

A property moves from an admin draft to a live market through the following stages. Each transition is recorded with an actor, a timestamp and an immutable audit entry.

Custodian verification

Before sign-off, the custodian works through a fixed checklist. Verification is all-or-nothing: every item must pass, or the listing is rejected with an itemised reason.

• Legal title — deed authenticity, registered owner, and a clean encumbrance/lien search.
• Independent valuation — a third-party appraisal within tolerance of the listed appraised value.
• SPV structure — a bankruptcy-remote vehicle whose cap table maps 1:1 to the proposed token supply.
• Insurance & condition — current insurance coverage and a satisfactory building condition report.
• Rent roll & occupancy — verified tenancy schedule supporting the stated occupancy and yield.
• Issuer KYC/AML — beneficial-owner identification and sanctions screening of the issuer.
• Custody arrangement — confirmation that title and tokens will be held segregated and insured.

The signed verification record (checklist results, appraisal reference, custodian signature and timestamp) is retained and surfaced in the property's public disclosures.

Listing states

Every listing is governed by an explicit state machine. Only the roles shown may trigger each transition.

// Example listing record
{
  "symbol": "EKO/NGN",
  "status": "live",
  "issuer_spv": "Eko Atlantic Tower SPV Ltd",
  "appraised_value": 72000000000,
  "total_tokens": 3840000,
  "reference_price": 1875000,
  "verification": {
    "custodian": "HX Custody Trust",
    "signed_at": "2026-07-30T09:14:00Z",
    "checklist_passed": true
  }
}

Tokenization & minting

On approval, the custodian mints exactly total_tokens units — one token per SPV share — and holds them in segregated custody. The invariant tokens_minted == spv_shares is enforced at mint time and reconciled by the auditor. Tokens are only ever created through this path; the exchange itself cannot mint.

Opening liquidity is seeded around the reference price so the book has depth on day one, and price discovery takes over from there.

Corporate actions

• Revaluation — periodic third-party appraisals update the reference valuation; the market may be briefly suspended around a revaluation.
• Rental distribution — net rental income is distributed pro-rata to holders of record on a snapshot date.
• Suspension — the custodian or admin can pause trading for a corporate action or investigation.
• Delisting — on sale or wind-down of the underlying asset, tokens are redeemed and burned, closing the market.

Matching engine

The engine matches orders with price-time priority:

• Price priority — orders that improve the price match first.
• Time priority — among orders at the same price, the earliest to arrive matches first (FIFO).

Trades always execute at the maker's resting price — the passive order sets the price and the aggressor accepts it. A taker sweeps as many price levels as needed until it is filled or its limit is reached.

Data structures

Each side of the book is a BTreeMap<Price, VecDeque<Order>>: the sorted map exposes best bid/ask in O(log n), and the per-price queue preserves arrival order for time priority. A hash index maps every resting order id to its (side, price) so cancellation is O(log n) rather than a scan.

Worked example

Book asks:  101 × 5   (maker A, earlier)
            101 × 5   (maker B, later)
            105 × 5

Taker: BUY 8 @ limit 110
 → fill 5 @ 101 against A   (price then time priority)
 → fill 3 @ 101 against B
 → 0 remaining; taker fully filled at the makers' prices.

Order types & time-in-force

Behaviour by combination

• Limit + GTC — matches what it can; any remainder rests on the book.
• Limit + IOC — matches what it can immediately; the remainder is cancelled.
• Limit + FOK — only executes if the entire quantity can fill immediately; otherwise rejected with no fills.
• Market + IOC — sweeps the opposite side until filled or liquidity is exhausted; never rests.

Order lifecycle

Every submission returns an execution report whose status is one of:

Order book & depth

The order book aggregates resting quantity by price into levels, returned best-first per side and depth-limited by the depth query parameter. The exchange UI renders cumulative depth bars, the spread (absolute and in basis points), and the mid price.

Market data

Executed trades form the tape, aggregated into OHLCV candlesticks (klines) at 1m, 5m, 15m, 1h, 4h and 1d intervals, plus rolling 24-hour statistics: last price, signed change, high, low, base volume and quote volume.

Fees & settlement

A taker fee of 0.10% of trade value applies to liquidity-taking fills; resting (maker) orders are not charged in this model. Fees and the order's notional value are shown in the order form before submission.

Settlement is atomic with matching: on each fill, base tokens and quote NGN move between the counterparties' custodied balances in the same operation, so positions and cash always reconcile against custody.

Custody model

Client tokens and cash are held by an independent, regulated custodian, segregated from HX Africa's own funds and insured. The custodian also holds legal title to each property's SPV, which is what gives the tokens real economic backing rather than being a mere IOU.

KYC & AML

Both issuers and investors are identity-verified. Investors complete KYC before funding; issuers undergo beneficial-owner identification and sanctions screening as part of listing verification. Ongoing transaction monitoring applies to both sides.

SPV structure

Each property is owned by its own bankruptcy-remote special-purpose vehicle. Isolating each asset in a dedicated SPV means a problem with one property — or with HX Africa itself — does not put other assets or client holdings at risk. The SPV's share register maps 1:1 to the token supply.

Audits & transparency

• Independent audits reconcile minted tokens against SPV shares.
• Live order books and a public trade tape make price formation observable.
• Valuation reports and the custodian's signed verification record are published per property.

Risk factors

Real-estate tokens carry risk: property values and rents can fall, occupancy can drop, liquidity can be thin for individual markets, and tokenized assets may be less liquid than listed equities. Nothing in this documentation is investment advice.

REST API

Base path /api. Prices are integer kobo; quantities are integer tokens. The public API is read & trade only — listing, verification and custody actions are performed off the public API through the Admin Console and Custodian Portal.

Submit an order

curl -X POST http://localhost:8080/api/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "symbol": "EKO/NGN",
    "side": "buy",
    "type": "limit",
    "price": 1250,
    "quantity": 100,
    "time_in_force": "GTC"
  }'

{
  "order_id": 1000,
  "symbol": "EKO/NGN",
  "status": "partially_filled",
  "filled_quantity": 40,
  "remaining_quantity": 60,
  "trades": [ { "price": 1249, "quantity": 40, "taker_side": "buy" } ]
}

Data types

Errors

Validation and routing errors return a JSON body with an error field. Business rejections (e.g. FOK that can't fully fill) come back as a normal execution report with status: "rejected" and a reject_reason.

WebSocket feed

Connect to /api/ws for a live stream of execution reports. Messages containing trades drive the price, chart and trade tape in real time.

const ws = new WebSocket(`ws://${location.host}/api/ws`);
ws.onmessage = (e) => {
  const report = JSON.parse(e.data);
  report.trades.forEach(t => console.log(t.price, t.quantity, t.taker_side));
};

Running locally

# build & test
cargo test

# run the exchange (API + UI on :8080)
cargo run

# custom port
PORT=8099 cargo run

Open http://localhost:8080/ for the landing page and /exchange.html for the trading terminal. On startup the server seeds demo markets, price history, a two-sided book, and a background market-maker. In production these markets would instead originate from the admin-listing / custodian-verification workflow described above.

Tokenomics & yield

• Appraised value — independent valuation of the whole asset.
• Tokens issued — fixed supply, equal to SPV shares.
• Implied market cap — last token price × supply.
• Net rental yield — projected annual net income as a % of value.
• Occupancy — share of the asset currently let.

Glossary

Disclaimer