Swagger API Explorer

Download the canonical Bitnob API v2 OpenAPI 3.0 specification and drop it straight into your code generator, API design tool, or Postman workspace.

Download API Specifications

Two artifacts are published — the JSON spec (best for code generators) and the YAML spec (best for human review and diffs). Both are byte-for-byte equivalent and describe Bitnob API v2 exactly.

OpenAPI 3.0 Specification Files

bitnob-api-v2.openapi.json

OpenAPI 3.0 specification in JSON — feed directly into openapi-generator, Prism, Spectral, or Stoplight

bitnob-api-v2.openapi.yaml

Same spec rendered as YAML — easier to read, review, and diff in pull requests

Quick Downloads

Click either link below to download the spec file directly — both files are served from this site's public/ directory, so no authentication is required.

Download bitnob-api-v2.openapi.json — OpenAPI 3.0 JSON specification
Download bitnob-api-v2.openapi.yaml — OpenAPI 3.0 YAML specification

What's in the spec

Every v2 endpoint: Identity, balances, addresses, transactions, withdrawals, exchange rates, trading, bulk transfers, payouts, cards, lightning, customers, and beneficiaries

Request & response schemas: Full JSON Schema definitions under components/schemas for every payload — fed directly to type-safe client generators

HMAC authentication: The X-Auth-Client, X-Auth-Timestamp, X-Auth-Nonce, and X-Auth-Signature headers are documented as a securityScheme so your generated client knows to prompt for them

RFC 7807 problem responses: Error responses reference a shared Problem schema so your client surfaces correlation_id and detail out of the box

What the spec gives you

Drop the spec into any OpenAPI-aware tool to get these capabilities for free

Live request testing

Import into Swagger UI, Stoplight, or Insomnia to send real requests — the spec's servers block pre-fills the base URL so you only need to paste your client_id and client_secret

Auth-aware clients

The HMAC securityScheme tells generators to emit helpers that take client_id + client_secret and sign requests automatically

Parameter validation

Every path, query, and body parameter has a JSON Schema with types, formats, enums, and examples — tools validate your input before sending

Response introspection

Every 2xx and 4xx response is fully typed, and the shared Problem schema makes RFC 7807 errors ergonomic to surface in UI

Code Generation

Generate client code and integration examples directly from the API specification.

Supported Languages

JavaScript/Node.js

ES6+ compatible code with async/await patterns and TypeScript definitions

Python

Python 3.7+ compatible requests-based client with type hints and error handling

PHP

PSR-4 compliant PHP client with Composer support and Laravel integration

Go

Idiomatic Go client with context support, structured errors, and comprehensive testing

cURL

Ready-to-execute cURL commands with proper headers, authentication, and payload formatting

Java

Java 11+ client using modern HTTP client with Jackson serialization and Spring Boot compatibility

C#/.NET

.NET 6+ compatible client with async patterns, dependency injection, and comprehensive logging

Ruby

Ruby 2.7+ compatible gem with ActiveRecord-style interfaces and Rails integration helpers

Getting Started

Step 1: Download the spec

Pick a format: bitnob-api-v2.openapi.json for code generators and validators, bitnob-api-v2.openapi.yaml for human review

Grab it: use the Quick Downloads links above, or curl -O the URL directly — no auth required

Verify the version: the spec's info.version is 2.0.0 — if you're still on v1, upgrade before generating clients

Step 2: Import into your tooling

Code generation: openapi-generator-cli generate -i bitnob-api-v2.openapi.yaml -g <language> produces a typed client in 40+ languages

API design tools: Import into Stoplight, Swagger Editor, or Insomnia to browse endpoints and try requests against sandbox

Postman: Prefer the pre-built Postman collection — it ships a pre-request script that auto-signs every call with HMAC-SHA256, which OpenAPI import alone does not wire up

CI contract testing: Feed the spec into Prism, Schemathesis, or Spectral to mock, fuzz, and lint your integration

API Coverage

Our Swagger documentation covers 100% of the Bitnob API surface area.

Core Endpoints

Identity — GET /api/whoami for workspace introspection

Balances — Per-currency workspace balances

Addresses — Deposit address generation across supported chains

Transactions — Paginated transaction history with filters

Withdrawals — On-chain and off-chain withdrawal flows

Exchange rates — Real-time quotes for supported pairs

Trading — Market, scheduled, and target orders

Bulk transfers — CSV/XLSX batch payouts with optional recurrence schedules

Payouts — Single and batch payouts to bank accounts and wallets

Cards — Virtual card issuing, funding, freeze/unfreeze, spend limits, and termination (the only DELETE in v2)

Lightning — Invoices, payments, and node operations

Customers — KYC onboarding and customer lifecycle

Beneficiaries — Saved payout recipients

Security & Authentication

HMAC-SHA256 request signing

Header-based auth

Every request carries X-Auth-Client, X-Auth-Timestamp, X-Auth-Nonce, and X-Auth-Signature — documented in the spec as a securityScheme so generated clients know to require them

Deterministic signing string

Signature is HmacSHA256(client_id:timestamp:nonce:body, client_secret) over a canonicalised (compact) JSON body — identical across languages

Environment Separation

Sandbox and production each issue their own client_id / client_secret pair — mixing them returns 401, so you cannot accidentally hit production with sandbox credentials

Replay protection

Timestamps older than a few minutes are rejected, and nonces are checked for uniqueness — your client must generate a fresh nonce per request

Integration Workflows

Review the spec: Open bitnob-api-v2.openapi.yaml in Swagger Editor or Stoplight to browse endpoints and data models

Download the spec: Pull bitnob-api-v2.openapi.json (or .yaml) into your repo so your build can regenerate clients deterministically

Generate the client: Run openapi-generator-cli (or your language's preferred generator) to produce a typed SDK

Validate against sandbox: Point your generated client at https://api.bitnob.com with sandbox client_id / client_secret and hit GET /api/whoami as a smoke test

Cut over to production: Swap in production client_id / client_secret and point base_url at https://api.bitnob.com — the same binary talks to both

Tool Integration

Postman Integration

Import swagger.yaml directly into Postman for advanced testing and automation workflows

OpenAPI Generator

Use openapi-generator CLI tool with our specification to create client libraries in 40+ languages

API Design Tools

Import specifications into Swagger Editor, Insomnia, or other API design platforms

Spec-driven workflows

Add these to your build pipeline to catch drift early

Contract testing — Run Schemathesis against sandbox to fuzz every endpoint with schema-derived inputs and flag any response that drifts from the spec

Linting — Add Spectral to CI to enforce your internal OpenAPI style rules on generated code

Mocking — Stand up Prism as a local mock server using the spec so frontend and mobile teams aren't blocked on backend availability

Diffing — Track bitnob-api-v2.openapi.json in your repo and run oasdiff on each upgrade to see exactly which endpoints, schemas, and enums changed

Tip

Pro Tip: Download bitnob-api-v2.openapi.yaml and feed it to openapi-generator-cli generate -i bitnob-api-v2.openapi.yaml -g <language> to produce a fully-typed client library. Commit the generated code (or at least the input spec) to your repo so upgrades are a one-line bump.

Note

Environment Safety: Always start with the sandbox client_id / client_secret pair and base_url=https://api.bitnob.com. Production credentials are issued separately and cannot be used interchangeably — mixing them returns 401 rather than silently moving real funds.