Liquidity.io Docs

Connect external ATS operators to Liquidity.io — cross-list securities, route orders, settle on-chain

For ATS operators who want to cross-list securities on Liquidity.io and route orders between venues.

What You Get

Cross-list your securities on Liquidity.io's orderbook
Receive trade.executed webhooks when your securities trade
On-chain settlement audit trail via SettlementRegistry
Real-time order book and market data feeds
FIX 4.4 + WebSocket + REST connectivity

Authentication

# Get access token
curl -X POST https://iam.liquidity.io/api/login/oauth/access_token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d scope=openid

# All subsequent calls
curl https://api.liquidity.io/v1/... \
  -H "Authorization: Bearer $TOKEN"

Cross-Listing Flow

Your ATS                             Liquidity.io ATS
  │                                       │
  │  POST /v1/securities                  │
  │  {asset_name, issuer, security_class} │
  │ ─────────────────────────────────►    │
  │                                       │
  │  POST /v1/webhooks                    │
  │  {url, events: ["trade.executed"]}    │
  │ ─────────────────────────────────►    │
  │                                       │
  │  Investor places order on your ATS    │
  │  POST /v1/orders                      │
  │ ─────────────────────────────────►    │
  │                                       │
  │     ◄── trade.executed webhook ──     │
  │     ◄── settlement.recorded     ──    │
  │     ◄── settlement.finalized    ──    │

API Endpoints

Securities

POST   /v1/securities                 Cross-list a security
GET    /v1/securities                 List your cross-listed securities
GET    /v1/securities/:id             Security detail + live quote
PATCH  /v1/securities/:id             Update metadata (restrictions, valuation)
DELETE /v1/securities/:id             Delist a security

Cross-List Request

{
  "asset_name": "Example Issuer Inc. — Series B Preferred Stock",
  "asset_type": "private_security",
  "security_class": "preferred_stock",
  "share_class": "Series B",
  "issuer_id": "iss_example_issuer_0001",
  "issuer_name": "Example Issuer Inc.",
  "issuer_type": "private_corporation",
  "cusip": null,
  "isin": null,
  "currency": "USD",
  "last_valuation_price": 44.00,
  "last_valuation_date": "2026-01-15",
  "restrictions": {
    "legend_required": true,
    "rule_144_holding_period_met": false,
    "transfer_restrictions": "Subject to issuer consent, right of first refusal, and applicable securities laws",
    "lock_up_expiry_date": null
  }
}

Orders

POST   /v1/orders                     Place an order (on behalf of your investor)
GET    /v1/orders                     List orders
GET    /v1/orders/:id                 Order status
DELETE /v1/orders/:id                 Cancel order

Order Request

{
  "security_id": "asset_corp_7g8h",
  "side": "buy",
  "order_type": "limit",
  "quantity": 1000,
  "price": 45.00,
  "time_in_force": "day",
  "investor_id": "inv_entity_meridian_growth_corp_0001",
  "account_id": "acct_buyer_corp_aa1b2c3d",
  "broker_dealer": {
    "firm_name": "Buyer BD Inc.",
    "crd_number": "705"
  }
}

Settlements

GET    /v1/settlements                List settlements for your securities
GET    /v1/settlements/:id            Settlement detail
GET    /v1/settlements/:id/txs        On-chain transaction hashes
GET    /v1/settlements/:id/verify     Verify on-chain (returns block explorer links)

Market Data

GET    /v1/securities/:id/quote       Real-time bid/ask/last
GET    /v1/securities/:id/book        Order book (L2)
GET    /v1/securities/:id/trades      Recent trades
GET    /v1/securities/:id/chart       OHLCV bars
WS     /v1/ws/book/:id               Streaming order book
WS     /v1/ws/trades/:id             Streaming trades

Webhook Events You Receive

Event	When	Key Fields
`trade.executed`	Order matched and trade recorded	Full trade payload (see below)
`settlement.recorded`	On-chain settlement tx submitted	`trade_id`, `tx_hash`, `block_number`
`settlement.finalized`	Settlement status changed	`trade_id`, `status` (SETTLED/FAILED/REVERSED)

This is the canonical payload matching the cross broker-dealer trade schema. All 7 entity types (corporation, LLC, trust, partnership, sole proprietorship, public company, SPV) use this same structure:

{
  "webhook_event": {
    "event_id": "evt_trade_corp_001",
    "event_type": "trade.executed",
    "endpoint": "POST /v1/webhooks/trade",
    "timestamp": "2026-03-22T14:32:00.000Z",
    "version": "2.0.0",
    "transaction_type": "trade",
    "blockchain_transaction_id": "0x3a9f...",
    "recipients": [
      {
        "recipient_id": "rec_001",
        "name": "Buyer BD Inc.",
        "role": "buyer_broker_dealer",
        "delivered_at": "2026-03-22T14:32:01.123Z",
        "delivery_status": "delivered"
      },
      {
        "recipient_id": "rec_002",
        "name": "Seller BD Corp.",
        "role": "seller_broker_dealer",
        "delivered_at": "2026-03-22T14:32:01.456Z",
        "delivery_status": "delivered"
      },
      {
        "recipient_id": "rec_003",
        "name": "Acme Transfer Agent Co.",
        "role": "transfer_agent",
        "delivered_at": "2026-03-22T14:32:01.789Z",
        "delivery_status": "delivered"
      }
    ]
  },
  "transaction": {
    "transaction_id": "txn_corp_1a2b3c4d",
    "transaction_type": "secondary_market_transfer",
    "status": "pending_compliance_clearance",
    "initiated_at": "2026-03-22T14:30:00.000Z",
    "description": "Secondary market transfer of Series B Preferred Stock — buyer-initiated",
    "security": {
      "asset_id": "asset_corp_7g8h",
      "asset_name": "Example Issuer Inc. — Series B Preferred Stock",
      "asset_type": "private_security",
      "security_class": "Preferred Stock",
      "share_class": "Series B",
      "cusip": null,
      "isin": null,
      "issuer_id": "iss_example_issuer_0001",
      "issuer_name": "Example Issuer Inc.",
      "issuer_type": "Private Corporation",
      "number_of_shares": 1000,
      "price_per_share": 45.00,
      "currency": "USD",
      "gross_trade_amount": 45000.00,
      "accrued_interest": 0.00,
      "commissions": {
        "buyer_broker_dealer": {
          "firm_name": "Buyer BD Inc.",
          "crd_number": "705",
          "commission_type": "flat_fee",
          "commission_rate": null,
          "commission_amount": 112.50,
          "currency": "USD"
        },
        "seller_broker_dealer": {
          "firm_name": "Seller BD Corp.",
          "crd_number": "250",
          "commission_type": "flat_fee",
          "commission_rate": null,
          "commission_amount": 112.50,
          "currency": "USD"
        },
        "total_commissions": 225.00
      },
      "net_trade_amount": 45225.00,
      "trade_execution_datetime": "2026-03-22T14:30:00.000Z",
      "price_determination_method": "negotiated",
      "bid_price": 44.50,
      "ask_price": 45.50,
      "last_valuation_price": 44.00,
      "last_valuation_date": "2026-01-15"
    },
    "settlement": {
      "settlement_date": "2026-03-24T00:00:00.000Z",
      "settlement_type": "bilateral",
      "settlement_status": "pending",
      "settlement_currency": "USD"
    },
    "restrictions": {
      "legend_required": true,
      "rule_144_holding_period_met": false,
      "transfer_restrictions": "Subject to issuer consent, right of first refusal, and applicable securities laws",
      "lock_up_expiry_date": null
    }
  },
  "buyer": {
    "investor_id": "inv_entity_meridian_growth_corp_0001",
    "account_id": "acct_buyer_corp_aa1b2c3d",
    "account_type": "entity",
    "broker_dealer": {
      "firm_name": "Buyer BD Inc.",
      "crd_number": "705",
      "finra_member": true
    },
    "compliance_ref": {
      "endpoint": "GET /v1/investors/inv_entity_meridian_growth_corp_0001/compliance",
      "description": "Fetch full KYC, KYB, accreditation, PEPs & Sanctions, adverse media, and transaction monitoring data for this investor."
    }
  },
  "seller": {
    "investor_id": "inv_indv_patricia_nguyen_0099",
    "account_id": "acct_seller_indv_corp",
    "account_type": "individual",
    "broker_dealer": {
      "firm_name": "Seller BD Corp.",
      "crd_number": "250",
      "finra_member": true
    },
    "compliance_ref": {
      "endpoint": "GET /v1/investors/inv_indv_patricia_nguyen_0099/compliance",
      "description": "Fetch full KYC, KYB, accreditation, PEPs & Sanctions, adverse media, and transaction monitoring data for this investor."
    }
  },
  "transfer_agent": {
    "firm_name": "Acme Transfer Agent Co.",
    "sec_registered": true,
    "sec_registration_number": "84-01234",
    "acknowledgment": {
      "acknowledged": true,
      "acknowledged_at": "2026-03-22T14:32:05.000Z",
      "transfer_instruction_id": "ti_corp_aa1b2c3d",
      "record_date": "2026-03-22T00:00:00.000Z",
      "units_to_transfer": 1000,
      "status": "pending_transfer"
    }
  }
}

On-Chain Settlement

Trades are recorded on the Liquidity EVM via SettlementRegistry:

Network	Chain ID	Registry
Devnet	8675311	Deployed via CREATE2
Testnet	8675310	Same deterministic address
Mainnet	8675309	Same deterministic address

The blockchain_transaction_id in the webhook payload maps to on-chain tx hashes queryable via the Block Explorer.

Supported Entity Types

The trade payload supports all 7 entity structures for issuers and investors:

Entity Type	Issuer Type	Example
Corporation	`private_corporation`	Example Issuer Inc.
LLC	`limited_liability_company`	Meridian Growth Partners LLC
Partnership	`limited_partnership`	Atlas Venture Partners LP
Public Company	`public_company`	NovaTech Industries Inc.
Sole Proprietorship	`sole_proprietorship`	Hamilton Equity Advisors
SPV	`special_purpose_vehicle`	Lighthouse Capital SPV I LLC
Trust	`trust`	Pacific Trust Holdings

Getting Started

Email partnerships@liquidity.io
Receive IAM credentials (client_id + client_secret)
Register webhook endpoints
Cross-list a test security on testnet
Execute a sandbox trade
Verify on-chain settlement on explorer

ATS Integration