API Reference

Base URL

Local and CI smoke tests reach the API through NGINX:

http://localhost:9999

The production compose file exposes the same public entrypoint on port 9999.

Client IDs and limits

The implementation has five predefined clients. The API keeps this small map in memory for fast invalid-client rejection, and PostgreSQL seeds the same limits in docker-entrypoint-initdb.d/rinha.dump.sql.

POST /clientes/{id}/transacoes

Submits a credit or debit transaction.

Request body

{
  "valor": 1000,
  "tipo": "c",
  "descricao": "deposito"
}

Successful response

The response uses snake_case JSON output generated by System.Text.Json source generation.

{
  "id": 1,
  "limite": 100000,
  "saldo": 1000
}

Status codes

Current implementation note

The intended Rinha contract treats a debit that would exceed the client’s limit as an unprocessable transaction. The current PostgreSQL function keeps the balance unchanged and returns the current balance when the limit update fails, so the API can return 200 with an unchanged balance for this case. If strict challenge behavior is required, adjust InsertTransacao/the route handler before documenting over-limit debits as guaranteed 422 responses.

GET /clientes/{id}/extrato

Returns the current account statement.

Successful response

{
  "saldo": {
    "total": 1000,
    "limite": 100000,
    "data_extrato": "2026-04-01T19:20:20.000000"
  },
  "ultimas_transacoes": [
    {
      "valor": 1000,
      "tipo": "c",
      "descricao": "deposito"
    }
  ]
}

The statement returns the latest 10 transactions ordered from newest to oldest.

Status codes

GET /healthz

Health check used by local smoke tests and GitHub Actions.

Responsibility split