# Coroutines first: notes on nRouter's Kotlin SDK

> Source: <https://dev.to/nrouterai/coroutines-first-notes-on-nrouters-kotlin-sdk-559n>
> Published: 2026-11-19 13:08:57+00:00

**Key takeaway:** The nRouter Kotlin SDK makes streaming a cold Flow that starts on collection and cancels with the collector, and marks RateLimit, Service and Transport errors as retryable via isRetryable so retry policy is a single when branch.

A Kotlin client for an API gateway can be a thin wrapper around blocking HTTP calls, with a coroutine adapter bolted on. The nRouter Kotlin guide goes the other way: the SDK is coroutines-first from the start — suspend functions for calls, a cold `Flow` for streaming, and typed error subclasses you can branch on.

Full guide: [https://nrouter.ai/docs/sdks/kotlin](https://nrouter.ai/docs/sdks/kotlin)

The guide publishes the artifact to your local Maven cache (`./gradlew clean check publishToMavenLocal`), then it's a normal Gradle dependency:

```
dependencies {
    implementation("ai.nrouter:nrouter-sdk-kotlin:3.1.2")
}
```

`NRouter()` reads `NROUTER_API_KEY` from the environment, targets `https://api.nrouter.ai/v1`, and dispatches on `Dispatchers.IO`, so calls don't block your caller's context. (For Android apps, the guide points to the separate `nrouter-sdk-android` artifact.)

```
suspend fun main() {
    val client = NRouter()

    val result = client.chatCompletions(
        JSONObject()
            .put("model", "nrouter/auto")
            .put("messages", listOf(mapOf("role" to "user", "content" to "Hello!")))
            .put("nrouter_optimize", "balanced")
    )

    val content = result.body.getJSONArray("choices")
        .getJSONObject(0).getJSONObject("message").getString("content")
    println(content)
    println("Request ID: ${result.meta.requestId}")
}
```

Two things worth noticing. The routing preference rides in the payload: `"nrouter/auto"` plus `"nrouter_optimize"` (`quality`, `balanced` or `cost`), with `"nrouter_cost_band"` (`low`, `mid`, `high`) available under `cost`. And the response carries `.meta` extracted from the gateway's `x-nr-*` headers, so request ID and cost metadata arrive as typed fields instead of header strings you parse yourself.

Streaming is a cold Flow — nothing moves until you collect:

```
client.messagesStream(
    JSONObject()
        .put("model", "nrouter/auto")
        .put("messages", listOf(mapOf("role" to "user", "content" to "Hello!")))
).collect { chunk ->
    print(chunk.delta)
}
```

Cold matters here: the request starts on collection and stops when the collector goes away, which is exactly the lifecycle behaviour you want in a view model or a Ktor handler.

Gateway refusals map to subclasses of `NRouterError`: `Request` (400, including `cost_band_unsatisfiable`), `GuardrailBlocked` (400), `Authentication` (401), `Credit` (402), `RateLimit` (429) and `Service` (503). The detail that makes this practical is `isRetryable` — true for `RateLimit`, `Service` and `Transport` — so a retry policy is one `when` branch instead of a table of status codes maintained by hand.

That's the whole shape: a JVM client that treats coroutines as the default rather than an add-on, and lets the gateway carry routing, budgets and guardrails behind one key. The guide has the full walkthrough: [https://nrouter.ai/docs/sdks/kotlin](https://nrouter.ai/docs/sdks/kotlin)
