openapi: 3.0.3
info:
title: CipherOwl Onchain Service API
description: CipherOwl blockchain compliance and risk assessment APIs (Screening, Risk & Reporting; Onchain; Private Data).
version: 2.1.0
servers:
- url: https://svc.cipherowl.ai
security:
- BearerAuth: []
tags:
- name: Onchain Service
description: Query blockchain balances and supported chain metadata across multiple networks.
paths:
/api/onchain/v1/chains/{chain}/balances:batchget:
post:
summary: Batch get balances
description: Retrieves balance information for up to 100 addresses on the same blockchain in a single efficient request. Partial failures are supported - if some addresses fail, successful results are still returned with error details for failed addresses.
operationId: OnChainService_BatchGetBalance
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1BatchGetBalanceResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
description: Network identifier - all addresses must be on this chain
in: path
required: true
schema:
type: string
example: bitcoin
tags:
- Onchain Service
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OnChainServiceBatchGetBalanceBody'
/api/onchain/v1/chains/{chain}/addresses/{address}/balance:
get:
summary: Get balance
description: Retrieves native currency balance and token holdings for a single blockchain address. Token balances are automatically included for chains that support them (Ethereum, Solana, XRP, Avalanche, etc.).
operationId: OnChainService_GetBalance
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetBalanceResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
description: Network identifier (bitcoin_mainnet, ethereum_mainnet, ethereum_classic_mainnet, xrp_mainnet, solana_mainnet, etc.)
in: path
required: true
schema:
type: string
example: bitcoin
- name: address
description: Blockchain address to query (format depends on chain)
in: path
required: true
schema:
type: string
example: 17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5
tags:
- Onchain Service
/api/onchain/v1/chains:
get:
summary: List chains
description: Returns metadata for all blockchain networks supported by this service, including chain identifiers, names, native units, and token support capabilities.
operationId: OnChainService_GetSupportedChains
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/onchainv1GetSupportedChainsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- Onchain Service
parameters: []
components:
schemas:
protobufAny:
type: object
properties:
'@type':
type: string
additionalProperties: {}
OnChainServiceBatchGetBalanceBody:
type: object
properties:
addresses:
type: array
items:
type: string
title: List of blockchain addresses to query (1-100 addresses)
description: 'Batch request for efficient multi-address queries on a single blockchain.
All addresses must be on the same network.
**Performance:**
- Single API call for up to 100 addresses
- Faster than individual requests
- Partial failures are handled gracefully'
title: Request for retrieving balances of multiple addresses
v1BatchGetBalanceResponse:
type: object
properties:
chain:
type: string
title: Network identifier matching the request
balances:
type: array
items:
type: object
$ref: '#/components/schemas/v1Balance'
title: Balance information for each queried address (same order as request)
description: 'Returns balance data for all requested addresses.
If individual addresses fail, their error field will contain details while other addresses return successfully.'
title: Response containing balance information for multiple addresses
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
type: object
$ref: '#/components/schemas/protobufAny'
onchainv1GetSupportedChainsResponse:
type: object
properties:
chains:
type: array
items:
type: object
$ref: '#/components/schemas/v1ChainInfo'
title: List of all supported blockchain networks with metadata
description: 'Returns metadata for all supported networks, useful for discovering available chains
and their capabilities before making balance queries.'
title: Response containing list of supported blockchain chains
v1GetBalanceResponse:
type: object
properties:
chain:
type: string
title: Chain identifier matching the request
balance:
$ref: '#/components/schemas/v1Balance'
title: Balance information including native and token balances
description: 'Returns the native currency balance and any token holdings for the requested address.
For chains that don''t support tokens, the tokens array will be empty.'
title: Response containing balance information for a single address
v1ChainInfo:
type: object
properties:
chain:
type: string
title: Unique network identifier for use in balance queries (e.g., "bitcoin_mainnet", "ethereum_mainnet")
name:
type: string
title: Full human-readable chain name for display (e.g., "Bitcoin", "Ethereum", "XRP Ledger")
symbol:
type: string
title: Native unit symbol used in Balance responses (e.g., "satoshi", "wei", "drop", "lamport")
supportsTokens:
type: boolean
title: Whether this chain supports querying token balances (true for Ethereum, Solana, XRP, Avalanche)
description: 'Provides essential information about each supported blockchain, including:
- Unique identifier for use in API requests
- Human-readable name for display purposes
- Native unit information for balance interpretation
- Token support capability
**Chain Identifiers:**
Currently supported chains include:
- bitcoin_mainnet, dogecoin_mainnet, litecoin_mainnet, bitcoin_cash_mainnet
- ethereum_mainnet, ethereum_classic_mainnet, avalanche_mainnet
- solana_mainnet, xrp_mainnet
- cardano_mainnet, polkadot_mainnet, stellar_mainnet, hedera_mainnet (coming soon)'
title: Metadata about a supported blockchain network
v1TokenBalance:
type: object
properties:
contract:
type: string
title: Token contract address or identifier (e.g., 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 for USDC on Ethereum)
name:
type: string
title: Human-readable token name (e.g., "USD Coin", "Wrapped Bitcoin")
symbol:
type: string
title: Token symbol (e.g., "USDC", "USDT", "WBTC")
balance:
type: string
title: Token balance in smallest unit as string (to preserve precision for large numbers)
decimals:
type: integer
format: int32
title: Number of decimal places for the token (typically 6-18)
type:
type: string
title: Token standard (e.g., "ERC-20", "SPL", "XRC-20")
description: 'Represents a single token holding (ERC-20, SPL, XRC-20, etc.) with full metadata.
Balance amounts are returned as strings to preserve precision for large numbers.
**Decimal Conversion Example:**
If balance="1000000" and decimals=6, the human-readable amount is 1.0 tokens'
title: Information about a token balance held by an address
v1Balance:
type: object
properties:
address:
type: string
title: Blockchain address that was queried
balance:
type: string
title: Native balance in smallest unit (satoshi, wei, lamport, drop) as string
unit:
type: string
title: Unit name of the native balance (e.g., "satoshi", "wei", "lamport", "drop")
tokens:
type: array
items:
type: object
$ref: '#/components/schemas/v1TokenBalance'
title: List of token balances held by this address (empty for non-token chains)
error:
type: string
title: Error message if the address query failed (empty string on success)
description: 'Contains the native currency balance and any token holdings.
Amounts are returned as strings in the smallest unit to preserve precision.
**Native Balance Units:**
- Bitcoin: satoshi (1 BTC = 100,000,000 satoshi)
- Ethereum/Ethereum Classic: wei (1 ETH = 1,000,000,000,000,000,000 wei)
- Solana: lamport (1 SOL = 1,000,000,000 lamport)
- XRP: drop (1 XRP = 1,000,000 drops)
**Error Handling:**
If an error occurs (invalid address, network issue, etc.), the error field will contain details
and the balance/tokens fields may be empty or partial.'
title: Balance information for a blockchain address
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth 2.0 access token obtained from /oauth/token using client credentials.