Kotlin SDK

The official Kotlin library for the CoinPaprika API provides a set of Retrofit interfaces and data models to access cryptocurrency market data. This allows for easy integration into any Android or Kotlin project that uses Retrofit for networking. This library provides the building blocks, not a pre-configured client. You are responsible for creating and configuring your own Retrofit instance.

Installation

Add the library dependency to your module’s build.gradle or build.gradle.kts file.

// build.gradle
implementation 'com.coinpaprika:apiclient:0.5.3'

You will also need to add dependencies for Retrofit, a JSON converter like Moshi, and an HTTP client like OkHttp if you haven’t already.

// build.gradle
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-moshi:2.9.0'
implementation 'com.squareup.moshi:moshi-kotlin:1.12.0'
implementation 'com.squareup.okhttp3:okhttp3:4.9.3'

Finally, ensure you have the INTERNET permission in your AndroidManifest.xml.

<uses-permission android:name="android.permission.INTERNET"/>

Quick Start

1. Create a Retrofit Instance

First, configure and build a Retrofit instance. You must provide the base URL and a converter factory.

import com.coinpaprika.apiclient.COINPAPRIKA_BASE_URL
import com.squareup.moshi.Moshi
import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
import retrofit2.Retrofit
import retrofit2.converter.moshi.MoshiConverterFactory

object RetrofitClient {
    private val moshi = Moshi.Builder()
        .add(KotlinJsonAdapterFactory())
        .build()

    val instance: Retrofit = Retrofit.Builder()
        .baseUrl(COINPAPRIKA_BASE_URL)
        .addConverterFactory(MoshiConverterFactory.create(moshi))
        .build()
}

2. Create a Service

Use your Retrofit instance to create an implementation of one of the library’s service interfaces, such as TickersService.

import com.coinpaprika.apiclient.TickersService

val tickersService: TickersService = RetrofitClient.instance.create(TickersService::class.java)

3. Make an API Call

Now you can use the service within a coroutine to make API calls.

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

// In your Activity, ViewModel, or other component
fun fetchTickers() {
    CoroutineScope(Dispatchers.IO).launch {
        try {
            // Get tickers quoted in USD
            val tickers = tickersService.getTickers(quotes = "USD")
            
            // Print the name and price of the first 5 tickers
            tickers.take(5).forEach { ticker ->
                val usdQuote = ticker.quotes?.get("USD")
                println("${ticker.name}: $${usdQuote?.price}")
            }
        } catch (e: Exception) {
            // Handle exceptions, e.g., network errors
            println("An error occurred: ${e.message}")
        }
    }
}

Authenticating with a paid plan

Paid plans (Starter / Pro / Business / Ultimate / Enterprise) live on a separate hostname, https://api-pro.coinpaprika.com/v1/, and require an API key in the Authorization header. The library doesn’t provide a Pro-aware base URL constant; configure it on your Retrofit builder along with an OkHttp Interceptor that injects the key on every request.

import okhttp3.Interceptor
import okhttp3.OkHttpClient
import com.squareup.moshi.Moshi
import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
import retrofit2.Retrofit
import retrofit2.converter.moshi.MoshiConverterFactory

object ProRetrofitClient {
    // CoinPaprika expects the bare API key, with no `Bearer ` prefix.
    private val authInterceptor = Interceptor { chain ->
        val key = System.getenv("COINPAPRIKA_API_KEY")
            ?: error("COINPAPRIKA_API_KEY is not set")
        val request = chain.request().newBuilder()
            .addHeader("Authorization", key)
            .build()
        chain.proceed(request)
    }

    private val httpClient = OkHttpClient.Builder()
        .addInterceptor(authInterceptor)
        .build()

    private val moshi = Moshi.Builder()
        .add(KotlinJsonAdapterFactory())
        .build()

    val instance: Retrofit = Retrofit.Builder()
        .baseUrl("https://api-pro.coinpaprika.com/v1/")
        .client(httpClient)
        .addConverterFactory(MoshiConverterFactory.create(moshi))
        .build()
}

Free-tier callers don’t need any of this. Keep the RetrofitClient from Quick Start pointed at COINPAPRIKA_BASE_URL without an interceptor.

Available Services

This library provides the following Retrofit service interfaces.

CoinsService

Used to fetch coin details and history.

getCoins(): Lists all available coins.
getCoin(id): Retrieves details for a specific coin ID.
getCoinEvents(id): Gets events related to a coin.
getCoinExchanges(id): Gets exchanges where a coin is listed.
getCoinMarkets(id, quotes): Gets market data for a coin.
getCoinTweets(id): Gets the latest tweets for a coin.
getCoinOHLCV(id, quotes): Gets the latest OHLCV data.
getHistoricalCoinOHLCV(...): Gets historical OHLCV data.

ExchangesService

Used to fetch data about exchanges.

getExchanges(quotes): Lists all exchanges.
getExchange(id, quotes): Retrieves details for a specific exchange.
getExchangeMarkets(id, quotes): Gets all markets for a specific exchange.

GlobalStatsService

Used to get global market data.

getGlobalStats(quotes): Retrieves global cryptocurrency market statistics.

PeopleService

Used to get information about people in the crypto space.

getPerson(id): Retrieves details for a specific person by ID.

SearchService

Used to perform searches.

search(...): Searches for coins, exchanges, people, and more.

TagsService

Used to get information about tags.

getTags(sortBy): Lists all tags.
getTag(id): Retrieves details for a specific tag.

TickersService

Used to fetch ticker price and market data.

getTicker(id, quotes): Retrieves the ticker for a specific coin ID.
getTickers(quotes, page): Lists tickers for all coins.

FAQs

How do I authenticate with Retrofit?

Add an OkHttp Interceptor that adds the Authorization header (bare key, no Bearer prefix) and point your Retrofit builder at https://api-pro.coinpaprika.com/v1/. See the “Authenticating with a paid plan” section above.

Where do I find coin IDs for service methods?

Use the Coverage Checker to discover canonical IDs (e.g., btc-bitcoin).

How do I request historical OHLCV?

Historical OHLCV requires a paid plan. Use the ProRetrofitClient from the Pro authentication section, then call CoinsService.getHistoricalCoinOHLCV(…) with start/end in ISO date format and a quote like “usd”.

What’s the recommended error handling?

Catch HttpException for non-2xx responses (e.g., 404, 429) and IOException for network failures; apply backoff before retries.

Error Handling

When using this library, you should wrap your API calls in a try-catch block to handle potential exceptions, such as HttpException from Retrofit for non-2xx responses or IOException for network failures.

import retrofit2.HttpException
import java.io.IOException

suspend fun fetchCoinData(coinId: String) {
    val coinsService = RetrofitClient.instance.create(CoinsService::class.java)
    try {
        val coin = coinsService.getCoin(coinId)
        println("Successfully fetched ${coin.name}")
    } catch (e: HttpException) {
        // Handle HTTP errors (e.g., 404 Not Found, 429 Too Many Requests)
        println("HTTP Error: ${e.code()} - ${e.message()}")
    } catch (e: IOException) {
        // Handle network errors (e.g., no internet connection)
        println("Network Error: ${e.message}")
    } catch (e: Exception) {
        // Handle other unexpected errors
        println("An unknown error occurred: ${e.message}")
    }
}

Requirements

Kotlin-enabled project (Android or pure Kotlin)
retrofit2
moshi (or another JSON converter)
okhttp3

License

This library is available under the MIT license. See the LICENSE file for more info.

AI & Tools

Get Started

API Reference

SDKs & Libraries

Installation

Quick Start

1. Create a Retrofit Instance

2. Create a Service

3. Make an API Call

Authenticating with a paid plan

Available Services

CoinsService

ExchangesService

GlobalStatsService

PeopleService

SearchService

TagsService

TickersService

FAQs

Error Handling

Requirements

License

​Installation

​Quick Start

​1. Create a Retrofit Instance

​2. Create a Service

​3. Make an API Call

​Authenticating with a paid plan

​Available Services

​CoinsService

​ExchangesService

​GlobalStatsService

​PeopleService

​SearchService

​TagsService

​TickersService

​FAQs

​Error Handling

​Requirements

​License

Installation

Quick Start

1. Create a Retrofit Instance

2. Create a Service

3. Make an API Call

Authenticating with a paid plan

Available Services

CoinsService

ExchangesService

GlobalStatsService

PeopleService

SearchService

TagsService

TickersService

FAQs

Error Handling

Requirements

License