> ## Documentation Index
> Fetch the complete documentation index at: https://developer.liquiditi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Definições

> Formatos de entrada, data, paginação e outras convenções da API da Liquiditi.

## URL base

Todas as requisições devem ser feitas para:

```
https://api.liquiditi.com.br/v1
```

## Autenticação

A API utiliza autenticação via **API Key**. Inclua o header `x-api-key` em todas as requisições.

| Header      | Valor            |
| ----------- | ---------------- |
| `x-api-key` | Sua Chave de API |

Para gerar sua chave, consulte [Autenticação](/api-reference/autenticacao).

## Formatos de dados

### Identificadores

Todos os identificadores (`ask_id`, `order_id` e similares) usam o formato **UUID v4**.

```
"ask_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
```

### Datas e horários

Datas e horários seguem o padrão **ISO 8601** com fuso explícito no valor.

```
"created_at": "2025-06-15T14:30:00Z"
```

Quando a API retorna apenas a data, sem horário, o formato é `YYYY-MM-DD`.

```
"settlement_date": "2026-12-11"
```

<Note>
  A plataforma segue a convenção ANBIMA para [dias úteis e feriados](https://www.anbima.com.br/feriados/feriados.asp).
</Note>

### Valores decimais

Em **todas** as respostas, a API serializa valores decimais (preços, rentabilidades, spreads etc.) como **string** no JSON, para preservar precisão. Isso vale para o esquema **Ask** (`ask_price`) e para o objeto **Asset** (`percentage_yield`, `prefixed_yield` e demais campos decimais).

```json theme={null}
"ask_price": "1025.50",
"percentage_yield": "1.0",
```

### Campos anuláveis

Alguns campos podem retornar `null` quando não se aplicam ao recurso ou ao tipo de ativo. Esses casos são indicados na documentação de cada endpoint.

```json theme={null}
"asset": {
  "asset_indexer": "CDI",
  "ask_percentage_yield": "1.0",
  "ask_prefixed_yield": null
}
```

## Paginação

Os endpoints que retornam listas aceitam os parâmetros abaixo:

| Parâmetro | Tipo    | Descrição                       |
| --------- | ------- | ------------------------------- |
| `limit`   | integer | Número máximo de resultados     |
| `offset`  | integer | Quantidade de resultados pulada |

### Exemplo

```bash theme={null}
curl -X GET "https://api.liquiditi.com.br/v1/asks?limit=10&offset=20" \
  -H "x-api-key: SUA_API_KEY"
```

## Erros

Respostas de erro seguem um formato padronizado com os campos `error` e `message`:

```json theme={null}
{
  "error": "not_found",
  "message": "Recurso não encontrado"
}
```

### Códigos HTTP

| Código | Descrição                                                                 |
| ------ | ------------------------------------------------------------------------- |
| `200`  | Requisição bem-sucedida                                                   |
| `201`  | Recurso criado com sucesso                                                |
| `400`  | Requisição inválida. Verifique os parâmetros enviados                     |
| `401`  | API Key ausente ou inválida                                               |
| `404`  | Recurso não encontrado                                                    |
| `409`  | Conflito. A ação não pode ser realizada no estado atual                   |
| `412`  | Pré-condição falhou. O recurso não está no estado esperado                |
| `422`  | Entidade não processável. Os dados são válidos, mas uma regra foi violada |