🔌 APIs

Bondis API — v1

Bondis exposes a signature-based REST & WebSocket API for trading, transfers, prime brokerage vaults (PBV), bridging visibility, and market data. All endpoints are versioned under /v1.

• Base URLs:

  • Mainnet: https://api.bondis.network/v1

  • Testnet: https://api-testnet.bondis.network/v1

• Transports: HTTPS (REST), WSS (WebSocket)

• Content-Type: application/json

• Auth: secp256k1 + keccak256 signatures (ECDSA)

---

Authentication

All state-changing requests (REST + WS commands) must be signed. Use a single Authorization header:

Authorization: Bondis alg=<secp256k1-keccak-eip712|secp256k1-keccak-raw>, h=<0x...>, sig=<0x...>

• alg defaults to secp256k1-keccak-eip712

• h: keccak256(CRR) where CRR is the Canonical Request Representation

• sig: signature over h

Canonical Request Representation (CRR)

CRR is the exact request you are sending, serialized deterministically:

CRR := join with "\n":
  METHOD (uppercase)
  PATH_WITH_QUERY (sorted query keys; RFC3986 encoding)
  BODY_JCS (RFC 8785 JSON canonicalization; "" if none)
  SEQ (uint64 as base-10 string)
  TIMESTAMP_MS (base-10 string)

• Digest is always h = keccak256(CRR)

• seq increments +1 for each state-changing call

• timestamp must be within ±30s

• Numbers in bodies are decimal strings (no sci-notation), up to 18 dp

• Unknown body fields are rejected

EIP-712 (default, wallet-friendly)

Sign typed data that wraps the digest:

{
  "types": {
    "EIP712Domain": [{"name":"name","type":"string"},{"name":"version","type":"string"}],
    "RequestHash": [{"name":"h","type":"bytes32"},{"name":"seq","type":"uint64"},{"name":"timestamp","type":"uint256"}]
  },
  "domain": {"name":"BondisAPI","version":"1"},
  "primaryType": "RequestHash",
  "message": {"h":"0x...", "seq":42, "timestamp":1736371200123}
}

Raw ECDSA (programmatic)

• alg=secp256k1-keccak-raw

• Sign keccak256(CRR); send sig=0x{r}{s}{v}

---

Determinism & Idempotency

• Monotonic seq: must increase by exactly +1 per account (REST & WS)

• Timestamps: ±30s window

• Idempotency:

  • REST: Idempotency-Key header (optional)

  • WS: dedupe by seq, per-item correlation IDs in batch commands

---

Rate Limits

No per-tx network fees. To prevent spam and ensure fair access, limits adjust by account age, balance, and traded volume. Exceeding limits returns HTTP 429 with a JSON error code REJECT_RATE_LIMIT.

---

Error Model

All errors use:

{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed",
    "details": { "...": "..." }
  }
}

Common code values:

• INVALID_SIGNATURE, INVALID_HASH, INVALID_SEQ, INVALID_TIMESTAMP, INVALID_ALG

• REJECT_RATE_LIMIT, REJECT_MIN_NOTIONAL, REJECT_MARGIN, INSUFFICIENT_BALANCE

• UNKNOWN_MARKET, NOT_FOUND

---

Trading

Bondis supports a compact schema for lower payloads: v:"1c" and short keys.

Key aliases (compact → verbose):

• m→market, s→side, r→role, t→type, p→price, q→size, cid→client_id, oid→order_id

• Enums: op: "n" (new), "c" (cancel). side: "b" (buy), "s" (sell)

Servers also accept verbose bodies but canonicalize to compact before hashing.

---

Bridges

Deposits are initiated on the origin chain by calling the Bondis Bridge contract (e.g., on Ethereum, Solana, L2s). The API offers visibility & reconciliation, not deposit initiation.

Status flow: pending_burn → pending_release → released (or failed). Check progress with GET /v1/bridge/{intentId}.