Liquidity.io Docs

Connect registered broker-dealers to Liquidity.io — execute trades, manage investor accounts, compliance reporting

For registered broker-dealers who execute trades on behalf of investors and need compliance, settlement, and reporting integration with Liquidity.io.

What You Get

Execute orders on Liquidity.io's ATS on behalf of your investors
Receive trade.executed webhooks with full commission breakdowns
Access compliance endpoints (KYC/KYB, accreditation, PEPs & sanctions)
On-chain settlement verification
FINRA OATS / CAT / ATS-N reporting data
Configurable commission structures (flat fee, percentage, tiered)

Authentication

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

Your organization's crd_number is verified against FINRA BrokerCheck during onboarding.

API Endpoints

Investor Accounts

POST   /v1/accounts                   Open investor account
GET    /v1/accounts                   List your investor accounts
GET    /v1/accounts/:id               Account detail
PATCH  /v1/accounts/:id               Update account (status, metadata)

Open Account Request

{
  "investor_id": "inv_entity_meridian_growth_corp_0001",
  "account_type": "entity",
  "broker_dealer": {
    "firm_name": "Buyer BD Inc.",
    "crd_number": "705",
    "finra_member": true
  }
}

Orders

POST   /v1/orders                     Place order for investor
GET    /v1/orders                     List orders (filterable by account)
GET    /v1/orders/:id                 Order status + fill details
DELETE /v1/orders/:id                 Cancel order

Trades

GET    /v1/trades                     List executed trades
GET    /v1/trades/:id                 Trade detail (includes commissions)
GET    /v1/trades/:id/settlement      Settlement status + on-chain txs

Compliance

GET    /v1/investors/:id/compliance   Full compliance profile
  └── KYC status, KYB (entity), accreditation, PEPs & sanctions,
      adverse media, transaction monitoring
GET    /v1/investors/:id/accreditation  Accreditation status + docs
POST   /v1/investors/:id/aml-check     Trigger AML screening

Commissions

GET    /v1/commissions                List commission records
GET    /v1/commissions/summary        Period summary (for billing)

Reporting

GET    /v1/reports/oats               FINRA OATS data (daily)
GET    /v1/reports/cat                CAT reporting data
GET    /v1/reports/ats-n              ATS-N quarterly data
GET    /v1/reports/trades             Trade blotter (CSV/JSON)
GET    /v1/reports/form-8949          Tax reporting (per investor)

Webhook Events You Receive

Event	When	Key Fields
`trade.executed`	Your investor's order was filled	Full payload with commissions
`settlement.recorded`	On-chain settlement submitted	`trade_id`, `tx_hash`
`settlement.finalized`	Settlement completed or failed	`trade_id`, `status`
`aml.flagged`	AML screening flagged a transaction	`investor_id`, `risk_score`, `reason`
`aml.cleared`	AML flag resolved	`investor_id`, `resolution`

Commission Structure in `trade.executed`

Each trade includes per-BD commission breakdown:

{
  "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
  }
}

Commission types: flat_fee, percentage, per_share, tiered.

Webhook Events You Send

Event	When	Action
`order.placed`	Your investor wants to trade	Liquidity.io executes on ATS
`order.cancelled`	Your investor cancels	Liquidity.io cancels if unfilled
`kyc.completed`	Your investor passed KYC on your side	Liquidity.io updates compliance
`account.opened`	You approved an investor account	Liquidity.io creates shadow account

Best Execution (FINRA 5310)

Liquidity.io's smart order router evaluates:

Internal ATS liquidity
16 external venues (Alpaca, IBKR, etc.) via Liquid Broker
Fee-aware routing (minimizes total cost including commissions)
Pre-trade compliance checks before routing

Best execution reports available via /v1/reports/best-execution.

Getting Started

Verify FINRA membership and CRD number
Email bd-partnerships@liquidity.io
Receive IAM credentials
Register webhook endpoints
Open test investor accounts on testnet
Execute sandbox trades

See also: Cross-Listing for full webhook payload specification.

Broker-Dealer Integration