Getting started with Tracer

Tracer is the layer your authorization or onboarding system calls before a transaction goes through. It runs your fraud, risk, and limit policies in milliseconds and returns ALLOW, DENY, or REVIEW. The decision then lives in one place instead of scattered across product code. What changes in your operation: decision logic stops living in scattered if statements across services. Rule changes ship through an API the same day instead of in the next release. Validation history gives you one place to investigate why a transaction received its decision. Trade-off: you add one HTTP call to the critical path of every transaction. The target is p99 under 80ms. In return, you get a single point for policy and decision history, and you remove duplicated logic from product code.

Who is this guide for? Developers (junior or senior) integrating Tracer for the first time. If you’re evaluating Tracer at a product or strategy level, start with What is Tracer. If you already have it running and need API mechanics, jump to the Tracer API quick start.

This guide walks you through setting up Tracer and running your first validation. In 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.

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
Validation history: Stored decisions for investigation and reporting
Product-agnostic: Validates transactions of any payment scheme, such as CARD, WIRE, PIX, or 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 it executes a transaction. It then acts on the decision (ALLOW, DENY, or REVIEW) according to your business logic.

How it works

How Tracer processes a validation request across its Validation, Rules, and Limits contexts and returns an ALLOW, DENY, or REVIEW decision — Figure 1. How Tracer works

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 has three bounded contexts:

Validation Context - Orchestrates requests, coordinates evaluation, and stores validation history
Rules Context - Manages rule definitions and expression evaluation
Limits Context - Manages spending limits and usage tracking

Prerequisites

Before you start, make sure you have:

Docker installed
PostgreSQL 17, with a database for Tracer (tracer in the examples below)
API Key for authentication

Infrastructure dependencies

Tracer requires the following components:

Component	Version	Purpose
PostgreSQL	17	Data persistence. Tracer uses its own `tracer` database on the shared Midaz PostgreSQL primary; it does not ship a dedicated instance.

Ports

Default ports used by Tracer services:

Service	Port	Description
Tracer API	4020	Main REST API
Reservation seam	4021	gRPC service the Midaz ledger calls to reserve limit capacity

Step 1: Run Tracer

Tracer ships as two public images on Docker Hub. Use the same tag for both:

Image	Role
`lerianstudio/midaz-tracer-migrations`	Applies the Tracer schema to the database, then exits
`lerianstudio/midaz-tracer`	Runs the Tracer API

The examples use the tag 4.3.0. Tracer does not apply migrations when it starts, so run the migration image first.

Apply the schema

docker run --rm \
  -e DB_HOST="your-postgres-host" \
  -e DB_PORT="5432" \
  -e DB_USER="your-postgres-user" \
  -e DB_PASSWORD="your-postgres-password" \
  -e DB_NAME="tracer" \
  -e DB_SSL_MODE="disable" \
  lerianstudio/midaz-tracer-migrations:4.3.0

The container exits with status 0 when the schema is up to date. You can run it again safely.

Start Tracer

docker run -d --name midaz-tracer \
  -p 4020:4020 \
  -e SERVER_ADDRESS=":4020" \
  -e DB_HOST="your-postgres-host" \
  -e DB_PORT="5432" \
  -e DB_USER="your-postgres-user" \
  -e DB_PASSWORD="your-postgres-password" \
  -e DB_NAME="tracer" \
  -e DB_SSL_MODE="disable" \
  -e ALLOW_INSECURE_TLS="true" \
  -e API_KEY_ENABLED="true" \
  -e API_KEY="your-secure-api-key" \
  lerianstudio/midaz-tracer:4.3.0

DB_SSL_MODE="disable" and ALLOW_INSECURE_TLS="true" fit a local PostgreSQL without TLS. In production, set DB_SSL_MODE to require or stronger, and leave ALLOW_INSECURE_TLS unset.

Essential environment variables

Variable	Description	Example
`SERVER_ADDRESS`	Listen address of the API	`:4020`
`DB_HOST`	PostgreSQL host	`your-postgres-host`
`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`
`LOG_LEVEL`	Log level	`INFO`, `DEBUG`, `ERROR`

For every variable, see Environment variables.

Step 2: Authenticate to the API

Tracer supports API key and plugin authentication. Plugin authentication takes precedence when you enable both, except on endpoints configured as API-key-only.

Deployment and authentication configuration	Auth header	When to use
Self-hosted, plugin auth enabled	`Authorization` header with a Bearer token	`PLUGIN_AUTH_ENABLED=true`, unless the endpoint is configured as API-key-only.
Self-hosted, API key auth	`X-API-Key` header	Plugin auth is disabled, or the endpoint is configured as API-key-only.
Lerian Cloud	`Authorization` header with a Bearer token	Always. The JWT is issued by Access Manager and carries the `tenantId` claim.

The remaining steps use the API key form because most local-development setups run that way. If plugin authentication applies to your request, replace X-API-Key: your-secure-api-key with Authorization: Bearer $JWT in every example.

API Key

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

GET /v1/rules
X-API-Key: your-secure-api-key

Bearer JWT

Include the JWT issued by Access Manager in the Authorization header:

GET /v1/rules
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tracer extracts the tenantId claim from the JWT and routes the request to the correct tenant database. You never pass the tenant identifier in a header, path, body, or rule scope. The token is the only source of truth.

cURL example

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

# Bearer JWT: List rules
curl -H "Authorization: Bearer $JWT" \
  https://tracer.sandbox.lerian.net/v1/rules

Keep API Keys and JWTs secure. Never expose them in client-side code or public repositories.

API key authentication is disabled by default (API_KEY_ENABLED=false). A production deployment must set API_KEY_ENABLED=true or PLUGIN_AUTH_ENABLED=true before you expose the service.

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	Period counting
`DAILY`	Maximum amount per day	A new count starts each day at the reset time (00:00 UTC by default)
`WEEKLY`	Maximum amount per week	A new count starts each Monday at the reset time (00:00 UTC by default)
`MONTHLY`	Maximum amount per month	A new count starts on the 1st of the month at the reset time (00:00 UTC by default)
`CUSTOM`	Maximum amount for a custom date range	One count for the whole range
`PER_TRANSACTION`	Maximum per single transaction	No count is kept

For detailed configuration of all limit types including reset times, time windows, and custom periods, see the Spending limits guide.

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
Payment scheme: Apply only to one scheme, such as CARD or PIX

Create a limit

curl -X POST http://localhost:4020/v1/limits \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Corporate Card Limit",
    "description": "Daily spending limit for corporate card transactions",
    "limitType": "DAILY",
    "maxAmount": "50000.00",
    "asset": "BRL",
    "scopes": [
      {
        "segmentId": "550e8400-e29b-41d4-a716-446655440000",
        "scheme": "CARD"
      }
    ]
  }'

Activate a limit

curl -X POST http://localhost:4020/v1/limits/{id}/activate \
  -H "X-API-Key: your-secure-api-key"

Limit lifecycle

Limits start in DRAFT status and follow the lifecycle DRAFT → ACTIVE → INACTIVE. Inactive limits can return to DRAFT for editing, or you can delete them. Activate a limit to start enforcement. For the full lifecycle and transition rules, see the Spending limits guide.

Monitor usage

Every POST /v1/validations response carries limitUsageDetails, with one entry per limit Tracer checked. Each entry holds the cap and the amount attempted. For a limit that keeps a count, it also holds the projected consumption of the current period: the amount already counted, the capacity that unconfirmed Midaz ledger reservations hold, and this transaction. The endpoint GET /v1/limits/{id}/usage reports the current period of the limit, for its most-used scope. For detailed configuration options, see the Spending limits guide.

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 (scheme, amount, asset, timestamp)
Account information
Optional: segment, portfolio, merchant, and custom

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST http://localhost:4020/v1/validations \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "550e8400-e29b-41d4-a716-446655440104",
    "scheme": "CARD",
    "subType": "credit",
    "amount": "1500.00",
    "asset": "BRL",
    "transactionTimestamp": "'"$TS"'",
    "account": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100"
    },
    "merchant": {
      "merchantId": "550e8400-e29b-41d4-a716-446655440103",
      "category": "5411",
      "name": "Test Merchant"
    },
    "metadata": {
      "channel": "mobile"
    }
  }'

The transactionTimestamp must be recent, which is why the example generates it. Tracer rejects a future timestamp with error code 0419 (1-minute clock skew tolerance). Tracer rejects a timestamp older than 24 hours with error code 0421.

requestId is the idempotency key. Send a new UUID for each attempt. If you repeat one, Tracer returns the decision it already recorded for that key. A rule you activated in between will not appear to take effect.

Tracer evaluates the rules and limits that apply to the transaction, 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 names the rules Tracer evaluated, the rules that matched, and the current limit usage. That detail helps with debugging and customer support.

Why Tracer returns a decision instead of blocking directly. Tracer is a decisioning layer, not an authorization gateway. The calling system holds the customer relationship and knows the channel. It decides what to do with a DENY. For example, your card-issuing system may honor a DENY for a stand-in pre-auth. It may still capture the request for analytics. By returning a decision, Tracer fits into any authorization flow without owning the customer-facing UX.

For complete payload structure and field details, see the API reference.

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:

curl -X POST http://localhost:4020/v1/rules \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block high-value card transactions",
    "description": "Deny card transactions above R$ 10,000",
    "expression": "amount > 10000",
    "action": "DENY",
    "scopes": [
      {
        "scheme": "CARD"
      }
    ]
  }'

Tracer preserves the name’s case and internal whitespace, trimming only leading and trailing whitespace before storage. Take the ruleId from the response and use it in the activate call below.

Activate a rule

curl -X POST http://localhost:4020/v1/rules/{id}/activate \
  -H "X-API-Key: your-secure-api-key"

Activation takes effect right away on the instance that served the activate call. A single-instance setup evaluates the rule on your next validation. When you run several instances behind a load balancer, the others pick the change up on their next rule sync. The interval is RULE_SYNC_POLL_INTERVAL_SECONDS, default 10. Deactivation propagates the same way.

Rule lifecycle

Rules follow the same lifecycle as limits: DRAFT → ACTIVE → INACTIVE. To start evaluation, activate the rule using POST /v1/rules/{id}/activate. You can deactivate and reactivate an active rule as needed. For detailed information about rule expressions and lifecycle management, see the Rules engine guide.

Observability

Tracer exposes endpoints for monitoring and observability.

Key metrics

Tracer exposes OpenTelemetry-compatible metrics via the OTLP exporter, plus custom application metrics:

tracer_auth_failures_total{reason} - Authentication failures by reason (missing_api_key, invalid_api_key)
tracer_validation_rollback_failures_total - Usage rollback failures during REVIEW decisions (eventual consistency gaps that self-correct at period boundaries)

Tracer’s built-in OpenTelemetry HTTP middleware provides standard HTTP request metrics automatically.

Verification

Confirm that everything works correctly.

Checklist

Tracer container started and healthy
API Key authentication working
Spending limit configured
Test transaction validated successfully
Rule created and activated

Next steps

From here, you can explore more advanced features:

Integration guide - Learn how to integrate your authorization system with Tracer
Rules engine - Write validation rules in CEL and manage their lifecycle
Spending limits - Configure and manage spending limits by scope and period
Validation history and compliance - Query validation history and use it in your compliance processes

Quick reference

The three flows you’ll use most:

Validate a transaction: POST /v1/validations. See the Tracer API quick start for the request shape.
Manage rules: /v1/rules (CRUD + lifecycle endpoints /activate, /deactivate, /draft). See the Rules engine guide.
Manage limits: /v1/limits (CRUD + lifecycle + /usage). See the Spending limits guide.

For the full endpoint catalog, request/response schemas, and error codes, see the API reference.

What your system should do with each decision

Decision	Tracer recommends	Your system should
`ALLOW`	Approval	Proceed with the transaction
`DENY`	Denial	Block the transaction and inform the user
`REVIEW`	Review	Queue for manual review in your system

Tracer returns decisions as recommendations. Your system must implement the appropriate action for each decision.

Overview

Guides

Console

Operations

Getting started with Tracer

Why use Tracer

What is Tracer

How it works

Core contexts

Prerequisites

Infrastructure dependencies

Ports

Step 1: Run Tracer

Apply the schema

Start Tracer

Essential environment variables

Step 2: Authenticate to the API

API Key

Bearer JWT

cURL example

Step 3: Configure a spending limit

Limit types

Scopes

Create a limit

Activate a limit

Limit lifecycle

Monitor usage

Step 4: Validate your first transaction

Submit a transaction for validation

Step 5: Create a validation rule

Activate a rule

Rule lifecycle

Observability

Key metrics

Verification

Checklist

Next steps

Quick reference

What your system should do with each decision

​Why use Tracer

​What is Tracer

​How it works

​Core contexts

​Prerequisites

​Infrastructure dependencies

​Ports

​Step 1: Run Tracer

​Apply the schema

​Start Tracer

​Essential environment variables

​Step 2: Authenticate to the API

​API Key

​Bearer JWT

​cURL example

​Step 3: Configure a spending limit

​Limit types

​Scopes

​Create a limit

​Activate a limit

​Limit lifecycle

​Monitor usage

​Step 4: Validate your first transaction

​Submit a transaction for validation

​Step 5: Create a validation rule

​Activate a rule

​Rule lifecycle

​Observability

​Key metrics

​Verification

​Checklist

​Next steps

​Quick reference

​What your system should do with each decision

Why use Tracer

What is Tracer

How it works

Core contexts

Prerequisites

Infrastructure dependencies

Ports

Step 1: Run Tracer

Apply the schema

Start Tracer

Essential environment variables

Step 2: Authenticate to the API

API Key

Bearer JWT

cURL example

Step 3: Configure a spending limit

Limit types

Scopes

Create a limit

Activate a limit

Limit lifecycle

Monitor usage

Step 4: Validate your first transaction

Submit a transaction for validation

Step 5: Create a validation rule

Activate a rule

Rule lifecycle

Observability

Key metrics

Verification

Checklist

Next steps

Quick reference

What your system should do with each decision