# RikkaHub

RikkaHub is an open-source chat app for Android. You can add a provider with an
OpenAI-compatible endpoint to it. Set that provider to the exchange. The
exchange sets a cap before the first token and charges for measured use.

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- RikkaHub installed from [rikka-ai.com](https://rikka-ai.com/download) or
  Google Play.

## 1. Add a provider

Open **Settings → Providers**. Tap the **+** button at the top of the page. In
the **Add Provider** dialog, keep the provider type **OpenAI**. Enter a name in
**Name**:

```
Liquid Inference
```

## 2. Set the key and the base URL

Paste your key into **API Key**:

```
sk-liquid-...
```

Replace the value in **API Base Url** with this URL:

```
https://router.inference.ai.exchange/v1
```

The base URL ends in `/v1`, because RikkaHub adds `/chat/completions` to it.
Keep the default value of **API Path**. Keep **Response API** off. Then tap
**Add**.

## 3. Add the models

Open the new provider and go to the **Models** tab. RikkaHub reads
`GET /v1/models` from the exchange and shows the names in a list. Open the list
with the button that shows the number of models. Select each name that you
want, for example:

```
liquid.auto
```

To use a name that is not in the list, tap **Add New Model** and type it in
**Model ID**. To get the current names, see the **Market** page. See
[Market data](https://inference.ai.exchange/docs/market.md).

RikkaHub sets the abilities of a model from the model ID. It does not know the
names of router models or presets. To use tools or a reasoning level with one of
these names, edit the model and turn on **Tool** or **Reasoning** in
**Abilities**.

## 4. Set a cap on each request

Open the **Advanced Settings** tab of the provider. Under **Custom Headers**,
add a header. Set **Header Name** to:

```
x-liquid-cap-usd
```

Set **Header Value** to the cap in USD:

```
1.00
```

RikkaHub sends the header with each request to this provider. The cap limits
each request. It does not limit the total charge of a conversation. Auto refuses
a request that has no price bound. See [Auto Router](https://inference.ai.exchange/docs/auto.md).

## The client on the receipt

The receipt names RikkaHub and its version as the client. You do not need to
set anything for this.

Do not set a value in **Settings → Preferences → Network → User-Agent**. If you
set one, the receipt does not name RikkaHub.

## Notes

- The exchange sets a cap on each request. To limit total spend, set a spending
  limit on the key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- If a model has the **Reasoning** ability and you select a reasoning level,
  RikkaHub sends `reasoning_effort`. The exchange sends a request with a
  reasoning effort only to an offer that accepts one.
- Use a preset for other purchasing rules. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Troubleshooting

| Symptom                                 | Cause and fix                                                                    |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| `401`                                   | The key is empty, wrong or expired. Paste it again into **API Key**.             |
| `403`                                   | Check the key's `spend` scope, address restriction and preset rules.             |
| `402`                                   | Add credit to the workspace or check the key's spend limit.                      |
| `404`                                   | Keep `/v1` at the end of the base URL, and keep `/chat/completions` as the path. |
| The model list is empty.                | Check the base URL and the key. RikkaHub reads the list with the same key.       |
| `model_not_found`                       | The model ID is not on the book. Use an exact name from the **Market** page.     |
| `auto_requires_price_bound`             | Add the `x-liquid-cap-usd` header in step 4.                                     |
| A request is refused for lack of funds. | The workspace balance cannot cover the cap. Add funds on the **Credits** page.   |

See [Errors](https://inference.ai.exchange/docs/errors.md) for the exchange's error codes and causes.

## Next steps

- [Z Code](https://inference.ai.exchange/docs/connect-zcode.md): a desktop agent with the same kind of provider.
- [Market data](https://inference.ai.exchange/docs/market.md): models and live offers.
- [API keys](https://inference.ai.exchange/docs/keys.md): scopes and spending limits.