Skip to main content

​
CoinPaprika 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 — 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.

​
ExchangesService

Used to fetch data about exchanges.

​
GlobalStatsService

Used to get global market data.

​
PeopleService

Used to get information about people in the crypto space.

​
SearchService

Used to perform searches.
  • search(...): Searches for coins, exchanges, people, and more.

​
TagsService

Used to get information about tags.

​
TickersService

Used to fetch ticker price and market data.

​
FAQs

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.
Use the Coverage Checker to discover canonical IDs (e.g., btc-bitcoin).
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”.

​
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.