@headlessoracle/client

Stop trading blind. Verify exchange status before every order with a cryptographically signed receipt that expires in 60 seconds.

TypeScript client for Headless Oracle V5 — typed wrappers for all endpoints, optional built-in signature verification, zero ambiguity about market state.

Installation

npm install @headlessoracle/client
# Optional: built-in receipt verification
npm install @headlessoracle/verify

Quick start

import { OracleClient } from '@headlessoracle/client'

const client = new OracleClient({ apiKey: 'ok_live_...' })

// Fetch a signed live receipt
const receipt = await client.getStatus('XNYS')

// Fail-closed: treat UNKNOWN as CLOSED
if (receipt.status !== 'OPEN') {
  throw new Error('Market not open — halting all execution')
}

With built-in verification

const client = new OracleClient({
  apiKey:    'ok_live_...',
  verify:    true,
  publicKey: '03dc27993a2c90856cdeb45e228ac065f18f69f0933c917b2336c1e75712f178',
})

// Throws OracleVerifyError if signature is invalid
const receipt = await client.getStatus('XNYS')

Batch queries

const batch = await client.getBatch(['XNYS', 'XNAS', 'XLON'])
for (const receipt of batch.receipts) {
  console.log(receipt.mic, receipt.status)
}

Schedule

const schedule = await client.getSchedule('XNYS')
console.log('Next open:', schedule.next_open)
console.log('Next close:', schedule.next_close)

API

Method	Auth	Description
getDemo(mic?)	No	Signed demo receipt (for testing)
getStatus(mic?)	Yes	Signed live receipt
getBatch(mics[])	Yes	Signed receipts for multiple exchanges
getSchedule(mic?)	No	Next open/close times
listExchanges()	No	All supported exchanges
getKeys()	No	Public key registry
getHealth()	No	Oracle liveness probe

Error handling

import { OracleClient, OracleError, OracleVerifyError } from '@headlessoracle/client'

try {
  const receipt = await client.getStatus('XNYS')
} catch (err) {
  if (err instanceof OracleError) {
    // HTTP error — err.statusCode, err.body
  } else if (err instanceof OracleVerifyError) {
    // Signature verification failed — err.reason
  }
}

Supported exchanges

MIC	Exchange	Timezone
XNYS	New York Stock Exchange	America/New_York
XNAS	NASDAQ	America/New_York
XLON	London Stock Exchange	Europe/London
XJPX	Japan Exchange Group	Asia/Tokyo
XPAR	Euronext Paris	Europe/Paris
XHKG	Hong Kong Exchanges	Asia/Hong_Kong
XSES	Singapore Exchange	Asia/Singapore

License

MIT