> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with Tracer

> Quickstart guide to set up and use Tracer, Lerian's real-time transaction validation and spending control platform.

This guide walks you through setting up **Tracer** and running your first validation. In just a few steps, you'll have a working environment ready to validate transactions in real time.

For step-by-step API instructions with request and response examples, see the [Tracer API quick start](/en/reference/tracer/tracer-api-quick-start).

## Why use Tracer

***

* **Real-time validation**: Make ALLOW/DENY/REVIEW decisions in under 80ms (p99)
* **Flexible rules**: Expression-based rule engine for custom business logic
* **Spending control**: Configure limits by account, portfolio, segment, and period
* **Complete audit trail**: Immutable validation records for SOX/GLBA compliance
* **Product-agnostic**: Supports any transaction type (Card, Wire, PIX, Crypto) |

By the end of this guide, you will:

* Understand Tracer architecture and core concepts
* Have a working development environment
* Run your first transaction validation
* Configure a spending limit

***

## What is Tracer

***

Tracer is a transaction validation platform that evaluates rules and limits and returns instant decisions. Your system calls Tracer before executing transactions and acts on the decision (ALLOW, DENY, or REVIEW) according to your business logic.

### How it works

<Frame caption="Figure 1. How Tracer works">
  <img src="https://mintcdn.com/lerian-49cb71fc/Mx6bI7Rs1ieyNuQg/images/en/docs/how-tracer-works.jpg?fit=max&auto=format&n=Mx6bI7Rs1ieyNuQg&q=85&s=32754b79d2e7356acdabdc9c26d45279" alt="" width="8072" height="1982" data-path="images/en/docs/how-tracer-works.jpg" />
</Frame>

In this flow:

* **Rules** evaluate expressions against the transaction context
* **Limits** check spending thresholds for applicable scopes
* **Decision** returns ALLOW, DENY, or REVIEW based on evaluation results

### Core contexts

Tracer is built around three bounded contexts:

1. **Validation Context** - Orchestrates requests, coordinates evaluation, records audit trail
2. **Rules Context** - Manages rule definitions and expression evaluation
3. **Limits Context** - Manages spending limits and usage tracking

***

## Prerequisites

***

Before you start, make sure you have:

* [ ] **Docker** and **Docker Compose** installed
* [ ] **Go 1.25.5+** (for local development)
* [ ] **PostgreSQL 16+** (included in Docker Compose)
* [ ] **API Key** for authentication

### Infrastructure dependencies

Tracer requires the following components:

| Component  | Version | Purpose                          |
| ---------- | ------- | -------------------------------- |
| PostgreSQL | 16+     | Data persistence and audit trail |

### Ports

Default ports used by Tracer services:

| Service    | Port | Description   |
| ---------- | ---- | ------------- |
| Tracer API | 8080 | Main REST API |
| PostgreSQL | 5432 | Database      |

***

## Step 1: Set up the environment

***

You can run Tracer with Docker Compose or locally for development.

### Option A: Docker Compose (recommended)

<Note>
  This is the fastest way to start. PostgreSQL starts automatically with the service.
</Note>

Clone the repository and start the services:

```bash theme={null}
# Clone the repository
git clone https://github.com/lerianstudio/tracer.git
cd tracer

# Setup environment
cp .env.example .env

# Start all services
make up
```

Verify service health:

```bash theme={null}
# Check Tracer health
curl http://localhost:4020/health

# Check readiness (database connection)
curl http://localhost:4020/readyz
```

### Option B: Local run

For development, you can run Tracer locally:

```bash theme={null}
# Set environment variables
export DB_HOST="localhost"
export DB_NAME="tracer"
export API_KEY="your-secure-api-key"
export API_KEY_ENABLED="true"
export SERVER_PORT="8080"
export LOG_LEVEL="INFO"

# Start the service
go run cmd/app/main.go
```

### Essential environment variables

| Variable          | Description                   | Example                  |
| ----------------- | ----------------------------- | ------------------------ |
| `DB_HOST`         | PostgreSQL host               | `localhost`              |
| `DB_NAME`         | PostgreSQL database name      | `tracer`                 |
| `API_KEY`         | API Key for authentication    | `your-secure-api-key`    |
| `API_KEY_ENABLED` | Enable API Key authentication | `true`, `false`          |
| `SERVER_PORT`     | API port                      | `8080`                   |
| `LOG_LEVEL`       | Log level                     | `INFO`, `DEBUG`, `ERROR` |

***

## Step 2: Authenticate to the API

***

Tracer uses API Key authentication for all requests.

### API Key authentication

Include the API Key in the `X-API-Key` header:

```http theme={null}
GET /v1/rules
X-API-Key: your-secure-api-key
```

### cURL example

```bash theme={null}
# Check API health (no authentication required)
curl http://localhost:4020/health

# List rules (authenticated)
curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:4020/v1/rules
```

<Warning>
  API Keys should be kept secure. Never expose your API Key in client-side code or public repositories.
</Warning>

***

## Step 3: Configure a spending limit

***

Spending limits control transaction amounts by scope and period. Create a limit using `POST /v1/limits`.

### Limit types

| Type              | Description                    | Reset behavior         |
| ----------------- | ------------------------------ | ---------------------- |
| `DAILY`           | Maximum amount per day         | Resets at midnight UTC |
| `MONTHLY`         | Maximum amount per month       | Resets on 1st of month |
| `PER_TRANSACTION` | Maximum per single transaction | No tracking needed     |

### Scopes

Apply limits to specific contexts:

* **Segment**: Apply to all accounts in a segment (e.g., corporate customers)
* **Portfolio**: Apply to accounts in a portfolio
* **Account**: Apply to a specific account
* **Transaction type**: Apply only to CARD, WIRE, PIX, or CRYPTO

### Limit lifecycle

Limits follow the same lifecycle as rules: `DRAFT` → `ACTIVE` → `INACTIVE`, and `INACTIVE` limits can transition back to `DRAFT` for re-editing. Activate a limit to start enforcement.

### Monitor usage

Query `GET /v1/limits/{id}/usage` to check current consumption. The `nearLimit` flag activates at 80% utilization for proactive management.

For detailed configuration options, see the [Spending limits guide](./spending-limits.mdx).

***

## Step 4: Validate your first transaction

***

With limits configured, you're ready to validate a transaction using `POST /v1/validations`.

### Submit a transaction for validation

Send a validation request with the transaction context including:

* Transaction details (type, amount, currency, timestamp)
* Account information
* Optional: segment, portfolio, merchant, and custom metadata

Tracer evaluates all active rules and limits, then returns one of three decisions:

| Decision | Meaning                                             | Your system should           |
| -------- | --------------------------------------------------- | ---------------------------- |
| `ALLOW`  | Transaction approved                                | Proceed with the transaction |
| `DENY`   | Transaction denied (rule matched or limit exceeded) | Block the transaction        |
| `REVIEW` | Requires manual review                              | Queue for human review       |

The response includes details about which rules were evaluated, which matched, and the current limit usage—useful for debugging and customer support.

For complete payload structure and field details, see the [API reference](/en/reference/tracer/validate-transaction).

***

## Step 5: Create a validation rule

***

Rules let you define custom business logic that evaluates during validation. Create a rule using the `POST /v1/rules` endpoint with an expression, action, and optional scopes.

For example, to block high-value transactions, you can create a rule with:

* **Expression**: `amount > 1000000` (amounts above R\$ 10,000)
* **Action**: `DENY`
* **Scope**: Apply only to `CARD` transactions

### Rule lifecycle

Rules are created in `DRAFT` status. To start evaluation, activate the rule using `POST /v1/rules/{id}/activate`. Active rules can be deactivated and reactivated as needed.

For detailed information about rule expressions and lifecycle management, see the [Rules engine guide](./rule-engine.mdx).

***

## Observability

***

Tracer exposes endpoints for monitoring and observability.

### Health endpoints

| Endpoint      | Description                          |
| ------------- | ------------------------------------ |
| `GET /health` | Liveness check (app running)         |
| `GET /ready`  | Readiness check (database available) |

### Key metrics

Tracer exposes Prometheus-compatible metrics:

* `tracer_validations_total{decision}` - Total validations by decision
* `tracer_validation_duration_seconds` - Validation latency histogram
* `tracer_rule_evaluations_total` - Total rule evaluations
* `tracer_limit_checks_total{result}` - Limit checks by result
* `tracer_auth_failures_total{reason}` - Authentication failures by reason
* `tracer_active_rules` - Number of active rules

***

## Verification

***

Confirm that everything is working correctly.

### Checklist

* [ ] Docker services started and healthy
* [ ] API Key authentication working
* [ ] Spending limit configured
* [ ] Test transaction validated successfully
* [ ] Rule created and activated

### Connectivity test

```bash theme={null}
# Check API health (liveness)
curl http://localhost:4020/health

# Check readiness (database connection)
curl http://localhost:4020/readyz
```

***

## Next steps

***

You've successfully set up Tracer and validated your first transaction. From here, you can explore more advanced features:

* **[Integration guide](./integration-guide.mdx)** - Learn how to integrate your authorization system with Tracer
* **[Rules engine](./rule-engine.mdx)** - Create sophisticated validation rules with CEL expressions
* **[Spending limits](./spending-limits.mdx)** - Configure and manage spending limits by scope and period
* **[Audit and compliance](./audit-compliance.mdx)** - Query validation history and understand the audit trail

***

## Quick reference

***

Key endpoints and concepts for quick lookup.

### Main endpoints

| Operation            | Method | Endpoint                    |
| -------------------- | ------ | --------------------------- |
| Health check         | GET    | `/health`                   |
| Readiness check      | GET    | `/ready`                    |
| Validate transaction | POST   | `/v1/validations`           |
| Get validation       | GET    | `/v1/validations/{id}`      |
| List validations     | GET    | `/v1/validations`           |
| Create limit         | POST   | `/v1/limits`                |
| Get limit            | GET    | `/v1/limits/{id}`           |
| Update limit         | PATCH  | `/v1/limits/{id}`           |
| Get limit usage      | GET    | `/v1/limits/{id}/usage`     |
| Create rule          | POST   | `/v1/rules`                 |
| Get rule             | GET    | `/v1/rules/{id}`            |
| Update rule          | PATCH  | `/v1/rules/{id}`            |
| Activate rule        | POST   | `/v1/rules/{id}/activate`   |
| Deactivate rule      | POST   | `/v1/rules/{id}/deactivate` |
| Delete rule          | DELETE | `/v1/rules/{id}`            |

### Transaction types

| Type     | Description               | subType examples                    |
| -------- | ------------------------- | ----------------------------------- |
| `CARD`   | Card-based transactions   | `debit`, `credit`, `prepaid`        |
| `WIRE`   | Wire transfers            | `domestic`, `international`, `ach`  |
| `PIX`    | Brazilian instant payment | `instant`, `scheduled`              |
| `CRYPTO` | Cryptocurrency            | `bitcoin`, `ethereum`, `stablecoin` |

### Decision types

| Decision | Description                | Your system should                        |
| -------- | -------------------------- | ----------------------------------------- |
| `ALLOW`  | Tracer recommends approval | Proceed with the transaction              |
| `DENY`   | Tracer recommends denial   | Block the transaction and inform the user |
| `REVIEW` | Tracer recommends review   | Queue for manual review in your system    |

<Note>
  Tracer returns decisions as recommendations. Your system is responsible for implementing the appropriate action based on each decision.
</Note>