Institutional API Guide

BASIS DIGITAL INFRASTRUCTURE LTD Institutional API for arbitrage, staking, treasury movement, reporting, and custody workflow automation LEI: 254900IX2F2KCWNSSS64 Seychelles IBC reg 248559 Capitalization: $35M Pre-Series A raised Production API: https://api.basis.pro/v1/ Primary institutional contact: [email protected]

1. Overview

The BASIS Institutional API provides programmatic access to account state, asset balances, staking workflows, reward accrual, withdrawals, order routing, reporting, and configurable risk controls. It is designed for institutions that require deterministic integration patterns, high-throughput messaging, and auditable operational workflows.

This API is intended for:

• Hedge funds

• Trading desks

• Custodians

• Market-makers

• Treasury teams operating managed digital asset balances

Key capabilities include:

• Account and balance retrieval

• Staking lifecycle management for BTC, ETH, SOL, and PAXG

• Reward reporting and historical accrual access

• Programmatic withdrawals to approved destinations

• Order submission and status retrieval for execution workflows

• Risk policy configuration through authenticated control endpoints

• Webhooks for low-latency downstream automation

• Immutable reporting and audit root retrieval

BHLE, the BASIS high-liquidity execution layer, is the infrastructure core behind the institutional stack. It delivers sub-50μs internal processing latency and sustains 100,000+ OPS for account events, risk checks, routing optimization, and ledger writes.

Supported staking booster tenors:

Booster	Bonus
14D	+10%
30D	+20%
90D	+50%
180D	+100% (2x)

Asset support is limited to BTC, ETH, SOL, and PAXG. PAXG is live and active. USDT is internal accounting only and cannot be deposited or withdrawn.

2. API Availability and Authentication

2.1 Base URL

https://api.basis.pro/v1/

Production conventions:

• Transport: HTTPS over TLS 1.3

• Payload format: application/json

• Response timestamps: ISO 8601 UTC

• Authentication timestamp header: Unix milliseconds UTC

• Decimal amounts: serialized as strings to preserve precision

• State-changing requests: should include Idempotency-Key

2.2 Versioning policy

BASIS uses path-based major versioning.

• Current major version: v1

• Non-breaking additions, such as new response fields or new optional request fields, may be introduced within v1

• Breaking changes are released under a new major path such as v2

• Deprecated fields remain supported for a minimum of 90 days after formal notice

• Institutional clients with dedicated environments receive change notices before breaking upgrades

• Clients should ignore unknown response fields to remain forward compatible

2.3 Authentication Flow

Each request must be signed with HMAC-SHA256 and include the exact headers below:

• X-BASIS-KEY

• X-BASIS-TIMESTAMP

• X-BASIS-SIGNATURE

Recommended additional headers:

• Content-Type: application/json

• Idempotency-Key: <uuid> for POST and PUT operations

Authentication flow:

1. Provision an institutional API key with the required scopes.

2. Bind source IP addresses and enable mTLS if required by your onboarding profile.

3. Generate a Unix millisecond timestamp.

4. Create the request body exactly as transmitted.

5. Compute the SHA-256 hash of the raw body bytes. For empty bodies, hash the empty string.

6. Build the canonical string as:

   • timestamp + "\n" + method + "\n" + path_with_query + "\n" + body_sha256_hex

7. Sign the canonical string with HMAC-SHA256 using your API secret.

8. Send the lowercase hex digest in X-BASIS-SIGNATURE.

Exact header example:

X-BASIS-KEY: bas_live_inst_01HZW6YF9C8P
X-BASIS-TIMESTAMP: 1774274521123
X-BASIS-SIGNATURE: 3b7be6d8b0f8f1e4d6d2c9988f41cc9a90cf1f376727233c45f7f0db2a53d9b9
Content-Type: application/json
Idempotency-Key: 2df7d6f5-c4f0-4627-bf86-4d01c4f0f4be

Validation rules on the server side:

• Timestamp skew tolerance: ±30 seconds

• Signature must match the raw request body and exact path with query string

• API key must have the required scope

• Source IP must match whitelist if enabled

• mTLS certificate must be valid if enforced for the key

HMAC-SHA256 pseudocode:

timestamp = unix_ms()
method = "POST"
path_with_query = "/v1/stake"
body = json_encode(request_body)
body_sha256_hex = sha256_hex(body)

canonical = timestamp + "\n" +
            method + "\n" +
            path_with_query + "\n" +
            body_sha256_hex

signature = hmac_sha256_hex(api_secret, canonical)

headers = {
  "X-BASIS-KEY": api_key_id,
  "X-BASIS-TIMESTAMP": timestamp,
  "X-BASIS-SIGNATURE": signature,
  "Content-Type": "application/json",
  "Idempotency-Key": uuid_v4()
}

2.4 Rate Limits

Rate limits apply per API key and are enforced over rolling one-second windows.

Tier	Sustained Limit	Recommended Use
Default	100 rps	Reporting, treasury ops, standard automation
Premium	500 rps	Active routing, market-making, high-frequency reconciliation

Rate limit headers:

• X-RateLimit-Limit

• X-RateLimit-Remaining

• X-RateLimit-Reset

When a client exceeds the limit, the API returns 429 Too Many Requests.

2.5 Security Features

BASIS supports institutional-grade controls at the transport, credential, and policy layers.

• IP whitelisting: restrict access to approved source ranges

• mTLS: optional or mandatory based on your integration profile

• Role-scoped keys: issue least-privilege keys such as balance:read, stake:write, or reports:read

• Key rotation: rotate credentials through POST /auth/rotate

• Idempotency support: protects state-changing requests from replay on network retries

• Immutable request tracing: all authenticated actions are mapped to request IDs and retained in the audit trail

• Destination controls: withdrawals can be restricted to approved addresses only

3. Endpoint Reference

Path	Method	Description	Auth Scope
/account	GET	Return institution profile, account identifiers, enabled products, and custody policy summary	account:read
/balance	GET	Return available, locked, staked, and pending balances by asset	balance:read
/stake	POST	Create a staking instruction with optional booster tenor	stake:write
/unstake	POST	Request partial or full release from an active stake	stake:write
/rewards	GET	List accrued and settled rewards by asset and date range	rewards:read
/withdrawal	POST	Create a withdrawal request to an approved destination	withdrawal:write
/withdrawal/{id}	GET	Return withdrawal status, fee, approval state, and network transaction details	withdrawal:read
/orders	POST	Submit an execution instruction with routing optimization parameters	orders:write
/orders	GET	List or filter orders by asset, status, and time range	orders:read
/reports/statement	POST	Generate account statements in JSON, CSV, or FIXML	reports:read
/reports/audit-root	GET	Return Merkle root and timestamp evidence for a reporting interval	reports:read
/auth/rotate	POST	Rotate an API key and return successor key metadata	auth:admin
/risk/config	GET	Read active risk controls and thresholds	risk:read
/risk/config	PUT	Update BSCB, DMM, and position monitor thresholds	risk:write
/webhooks	POST	Register or update webhook destinations and event subscriptions	webhooks:write
/webhooks	GET	List active webhook endpoints and subscribed event types	webhooks:read

Common success envelope:

Field	Type	Description
request_id	string	Server-generated trace identifier
server_time	string	ISO 8601 UTC timestamp
status	string	ok, accepted, or endpoint-specific success state
data	object	Endpoint payload

Common error envelope:

Field	Type	Description
request_id	string	Trace identifier for support and audit
server_time	string	ISO 8601 UTC timestamp
status	string	error
error.code	string	Machine-readable error code
error.message	string	Human-readable summary
error.details	object	Optional field-level detail

Common HTTP statuses:

Status	Meaning
200	Request completed successfully
201	Resource created
202	Request accepted for asynchronous processing
400	Validation error
401	Authentication failed
403	Scope or policy denied
404	Resource not found
409	State conflict or idempotency collision
429	Rate limit exceeded
500	Internal service error
503	Temporary service degradation

4. Request and Response Examples

All numeric amounts are represented as strings. For GET endpoints, the request JSON below represents query parameters.

4.1 GET /balance

Request JSON:

{
  "include_locked": true,
  "include_valuation": true,
  "valuation_currency": "USD"
}

Response JSON:

{
  "request_id": "req_01JV7CPEA7CVY2H2QF4M1P9Q8V",
  "server_time": "2026-03-23T14:00:01.104Z",
  "status": "ok",
  "data": {
    "account_id": "acc_inst_00127",
    "valuation_currency": "USD",
    "balances": [
      {
        "asset": "BTC",
        "available": "12.54000000",
        "locked": "0.75000000",
        "staked": "8.00000000",
        "pending_withdrawal": "0.00000000",
        "usd_value": "1073760.54"
      },
      {
        "asset": "ETH",
        "available": "185.25000000",
        "locked": "10.00000000",
        "staked": "60.00000000",
        "pending_withdrawal": "0.00000000",
        "usd_value": "654922.75"
      },
      {
        "asset": "SOL",
        "available": "4200.00000000",
        "locked": "0.00000000",
        "staked": "1500.00000000",
        "pending_withdrawal": "25.00000000",
        "usd_value": "769500.00"
      },
      {
        "asset": "PAXG",
        "available": "95.50000000",
        "locked": "0.00000000",
        "staked": "20.00000000",
        "pending_withdrawal": "0.00000000",
        "usd_value": "440267.50"
      }
    ],
    "totals": {
      "usd_value": "2938450.79"
    }
  }
}

4.2 POST /stake

Example: staking BTC with a 90D booster

Request JSON:

{
  "asset": "BTC",
  "amount": "2.50000000",
  "booster": "90D",
  "auto_renew": true,
  "source_account": "main",
  "client_reference": "fund-alpha-btc-20260323-01"
}

Response JSON:

{
  "request_id": "req_01JV7CQ3W3TYZXAH6M0M5CGY0B",
  "server_time": "2026-03-23T14:02:11.284Z",
  "status": "accepted",
  "data": {
    "stake_id": "stk_01JV7CQ3X8A4JH4G4CNQ8PX4MZ",
    "asset": "BTC",
    "amount": "2.50000000",
    "booster": "90D",
    "term_days": 90,
    "booster_bonus_pct": "50",
    "base_reward_rate_apr": "0.0600",
    "effective_reward_rate_apr": "0.0900",
    "auto_renew": true,
    "source_account": "main",
    "status": "pending_settlement",
    "submitted_at": "2026-03-23T14:02:11.284Z",
    "expected_settlement_at": "2026-03-23T14:02:12.000Z",
    "maturity_at": "2026-06-21T14:02:12.000Z",
    "client_reference": "fund-alpha-btc-20260323-01"
  }
}

4.3 POST /unstake

Request JSON:

{
  "stake_id": "stk_01JV7CQ3X8A4JH4G4CNQ8PX4MZ",
  "amount": "1.00000000",
  "destination_account": "main",
  "client_reference": "fund-alpha-unstake-20260323-01"
}

Response JSON:

{
  "request_id": "req_01JV7CRSH3E0HDKRE98VP4EF0N",
  "server_time": "2026-03-23T14:05:08.440Z",
  "status": "accepted",
  "data": {
    "unstake_id": "ustk_01JV7CRSJ3QBV3R9N9R4N2ZZ6K",
    "stake_id": "stk_01JV7CQ3X8A4JH4G4CNQ8PX4MZ",
    "asset": "BTC",
    "amount": "1.00000000",
    "destination_account": "main",
    "status": "queued",
    "submitted_at": "2026-03-23T14:05:08.440Z",
    "estimated_settlement_at": "2026-03-23T14:05:12.000Z",
    "client_reference": "fund-alpha-unstake-20260323-01"
  }
}

4.4 GET /rewards

Request JSON:

{
  "asset": "BTC",
  "from": "2026-03-01",
  "to": "2026-03-23",
  "granularity": "daily"
}

Response JSON:

{
  "request_id": "req_01JV7CT2N9M43ZV3VJYJTRTH0T",
  "server_time": "2026-03-23T14:08:33.015Z",
  "status": "ok",
  "data": {
    "account_id": "acc_inst_00127",
    "asset": "BTC",
    "from": "2026-03-01",
    "to": "2026-03-23",
    "granularity": "daily",
    "rewards": [
      {
        "date": "2026-03-21",
        "accrued": "0.00041000",
        "settled": "0.00000000",
        "status": "accrued"
      },
      {
        "date": "2026-03-22",
        "accrued": "0.00041200",
        "settled": "0.00000000",
        "status": "accrued"
      },
      {
        "date": "2026-03-23",
        "accrued": "0.00041500",
        "settled": "0.00000000",
        "status": "accrued"
      }
    ],
    "totals": {
      "accrued": "0.00984200",
      "settled": "0.00000000",
      "usd_value": "842.11"
    }
  }
}

4.5 POST /withdrawal

Request JSON:

{
  "asset": "BTC",
  "amount": "0.75000000",
  "network": "BTC",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "memo": null,
  "source_account": "main",
  "client_reference": "fund-alpha-wd-20260323-01"
}

Response JSON:

{
  "request_id": "req_01JV7CVTRKW7ZW7A6N3PZQ50JD",
  "server_time": "2026-03-23T14:11:27.889Z",
  "status": "accepted",
  "data": {
    "withdrawal_id": "wd_01JV7CVTTFM7F8XMNZY6T2RD7F",
    "asset": "BTC",
    "amount": "0.75000000",
    "network": "BTC",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "fee_estimate": "0.00012000",
    "net_amount_estimate": "0.74988000",
    "status": "pending_authorization",
    "source_account": "main",
    "created_at": "2026-03-23T14:11:27.889Z",
    "estimated_completion_seconds": 45,
    "client_reference": "fund-alpha-wd-20260323-01"
  }
}

5. Webhooks and Callbacks

BASIS webhooks provide low-latency event delivery to client systems for reconciliation, treasury movement, reward accounting, and downstream execution workflows.

Event payload shape:

{
  "event_id": "evt_01JV7CXR1XKJ59EBB2SY6P1P0W",
  "type": "stake.settled",
  "created_at": "2026-03-23T14:13:05.121Z",
  "account_id": "acc_inst_00127",
  "data": {
    "stake_id": "stk_01JV7CQ3X8A4JH4G4CNQ8PX4MZ",
    "asset": "BTC",
    "amount": "2.50000000",
    "status": "settled"
  }
}

Event types:

Event Type	Trigger	Core Data
balance.update	Any confirmed balance state change	asset, available, locked, staked, pending_withdrawal
stake.settled	Stake instruction reaches settled state	stake_id, asset, amount, status, maturity_at
reward.accrued	Reward accrual is posted to the account ledger	asset, accrued, period_start, period_end
withdrawal	Withdrawal state changes through its lifecycle	withdrawal_id, asset, amount, status, tx_hash

Signature verification:

• Each webhook includes X-BASIS-WH-SIG

• Compute HMAC-SHA256 over the raw request body using the webhook secret configured at registration

• Compare the resulting lowercase hex digest to X-BASIS-WH-SIG using a constant-time comparison

• Deduplicate using event_id

Verification pseudocode:

raw_body = request_body_bytes
expected_sig = hmac_sha256_hex(webhook_secret, raw_body)
provided_sig = header("X-BASIS-WH-SIG")

if !constant_time_equals(expected_sig, provided_sig):
    reject_request()

Delivery guarantees:

• Delivery model: at-least-once

• Acknowledgement rule: any 2xx response marks the event delivered

• Retry strategy: exponential back-off on non-2xx responses or connection failure

• Retry window: up to 24 hours

• Ordering: best effort per destination, not guaranteed across event types

• Consumer requirement: webhook handlers should be idempotent

Webhook registration endpoint:

POST /webhooks

Registration payload fields:

• url: your HTTPS endpoint

• events: array of event types

• secret: shared signing secret

• active: boolean flag

6. Execution Infrastructure

BHLE is the execution and settlement fabric that sits behind institutional API traffic. It is optimized for deterministic routing, pre-trade control enforcement, ledger consistency, and fast acknowledgement paths.

BHLE architecture overview:

• Gateway layer for authenticated HTTP and FIX ingress

• Deterministic pre-trade and pre-withdrawal policy checks

• In-memory state engine for balances, locks, and exposure views

• Routing optimization layer for order and conversion instructions

• Append-only ledger writer for settlement state

• Replicated audit stream for reporting and reconciliation

• Sub-50μs internal processing latency

• Sustained throughput above 100,000+ OPS

Co-location and institutional connectivity:

• Dual-site co-location topology is available for approved institutional clients

• Equinix cross-connect connectivity is supported for private low-latency access

• FIX 4.4 sessions are available for clients that prefer standardized order flow and drop copy patterns

• Site-level provisioning details are shared during onboarding

Connectivity modes:

Mode	Transport	Typical Gateway Latency	Best Use Case
Public Internet	HTTPS over TLS 1.3	2 ms to 30 ms path-dependent	Treasury operations, reporting, standard automation
Cross-connect	Private circuit via Equinix	250μs to 900μs typical	Active execution, low-latency reconciliation
FIX-over-TLS	FIX 4.4 over TLS	Acknowledgement under 1 ms p99	Trading desks, market-makers, drop copy

Latency figures represent BASIS edge behavior under normal operating conditions and exclude client-side network variance.

Atomic clock synchronization:

• Gateway, engine, and ledger events are stamped against atomic-clock synchronized UTC sources

• Timestamp ordering is preserved across API events, webhooks, reports, and FIX sessions

• Time synchronization supports deterministic reconciliation and precise audit sequencing

7. Supported Assets

Asset	Native Deposit	Staking Token	Min Stake	Withdrawal Network
BTC	Yes	BTC	0.01000000	Bitcoin
ETH	Yes	ETH	0.25000000	Ethereum
SOL	Yes	SOL	5.00000000	Solana
PAXG	Yes	PAXG	0.10000000	Ethereum (ERC-20)

Notes:

• Supported assets are limited to BTC, ETH, SOL, and PAXG only

• PAXG is live and fully active for deposit, staking, rewards, and withdrawal

• USDT is internal accounting only and cannot be deposited or withdrawn

8. Risk Controls

BASIS applies account-level and workflow-level risk controls before balance mutation, execution submission, or withdrawal release. Institutional clients can review and update control settings through /risk/config, subject to scope and approval policy.

Risk controls:

Control	Description	Default
BSCB	Balance Sufficiency Circuit Breaker. Blocks stake, order, or withdrawal requests that would violate available balance or reserve thresholds	Enabled
DMM	Drawdown Mitigation Monitor. Throttles new risk when account-level drawdown thresholds are breached	Enabled
Position Monitor	Enforces concentration and exposure thresholds by asset, tenor, and workflow type	Enabled

GET /risk/config returns the active account policy.

PUT /risk/config updates policy thresholds, subject to risk:write scope and internal approval policy.

Example risk configuration payload:

{
  "bscb": {
    "enabled": true,
    "min_operational_buffer_pct": "2.00"
  },
  "dmm": {
    "enabled": true,
    "daily_drawdown_limit_pct": "5.00"
  },
  "position_monitor": {
    "enabled": true,
    "single_asset_concentration_limit_pct": "40.00"
  }
}

Operational notes:

• Risk policy changes are fully audited

• Policy updates can be staged for activation at a future timestamp

• Rejected requests return detailed policy failure reasons in error.details

9. Reporting and Audit Trail

BASIS maintains a 7-year immutable operational and ledger log for institutional accounts. Every authenticated API action, balance mutation, stake lifecycle event, reward accrual, withdrawal event, and risk policy change is preserved for audit and reconciliation.

Reporting capabilities include:

• Statement generation through /reports/statement

• Export formats: JSON, CSV, FIXML

• Interval-level audit anchoring through /reports/audit-root

• RFC 3161 TSA timestamps for report evidence

• Merkle-root proofs for statement integrity verification

Typical reporting workflow:

1. Submit a statement generation request to POST /reports/statement

2. Specify account, date range, and desired format

3. Retrieve the generated statement and associated integrity metadata

4. Verify the returned Merkle root against /reports/audit-root

5. Store the accompanying RFC 3161 timestamp token for external audit evidence

Recommended statement fields:

• Account identifier

• Asset balances by day or interval

• Stake opens and closes

• Reward accrual and settlement

• Withdrawal requests and completion state

• Order submissions and acknowledgements

• Risk policy changes

• Request IDs and server timestamps

10. Service Level Agreement

Service Metric	Target
API uptime	99.98%
Order acknowledgement	<1 ms p99
Webhook delivery	<500 ms
Withdrawal completion	<60 s

SLA notes:

• Targets apply to normal operating conditions

• Client-side network path variance is excluded

• Planned maintenance windows are notified in advance

• Policy-based holds, destination approval workflows, or external network congestion may affect individual settlement outcomes

11. Research References

Selected Base58 Labs research papers from 2026:

1. Base58 Labs, "Deterministic Routing Optimization Under Stochastic Latency", 2026

2. Base58 Labs, "Atomic Time Ordering for Digital Asset Audit Trails", 2026

3. Base58 Labs, "Adaptive Liquidity Recycling for Yield and Arbitrage Portfolios", 2026

4. Base58 Labs, "Secure Multi-Signature Orchestration for Institutional Settlement", 2026

5. Base58 Labs, "Low-Latency Risk Gating with Balance Sufficiency Circuit Breakers", 2026

12. Contact

• [email protected]

• NOC: [phone]

Client assets are segregated at wallet, ledger, and reporting layers. Withdrawal release policies support approved destination lists, role-based authorization chains, and multi-sig custody controls. Hot wallet exposure is policy-limited, with excess balances swept to segregated cold custody. Audit evidence is available through immutable statements, Merkle-root verification, and RFC 3161 timestamp records.