Tracer API quick start

This guide is intended for developers. If you’re looking for a business-level overview of what Tracer does, see What is Tracer?.

Get Tracer running in minutes. This guide walks you through the complete journey, from creating your first rule and spending limit to validating a transaction and reviewing the audit trail.

Before you begin

You need:

A running Tracer instance
Credentials for one of the two supported auth modes

All examples use cURL. Replace $API_KEY with your API key (single-tenant) or $JWT with your Bearer token (multi-tenant), and https://tracer.lerian.io with your Tracer URL.

Auth mode depends on deployment. Single-tenant deployments use X-API-Key. Multi-tenant deployments (SaaS / BYOC Multi-Tenant) use Authorization: Bearer <jwt> — the JWT is issued by Access Manager and carries the tenantId claim. In multi-tenant mode, replace every -H "X-API-Key: $API_KEY" in this guide with -H "Authorization: Bearer $JWT". Tracer resolves the tenant from the token automatically — never pass the tenant identifier in any other field. See Multi-tenancy for the model.

Step 1: Create a rule

Create a validation rule with a CEL expression. Rules are always created in DRAFT status — they do not affect transactions until you activate them.

API reference: Create rule

cURL

curl -X POST "https://tracer.lerian.io/v1/rules" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Block high-value transactions",
   "description": "Deny transactions above BRL 10,000 for card payments",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "transactionType": "CARD"
     }
   ]
 }'

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "description": "Deny transactions above BRL 10,000 for card payments",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}

Save the ruleId. You will use it to activate the rule.

Monetary values (transaction amount, spending limit maxAmount, and usage counters) are expressed as decimal strings, for example "1500.00" or "10000.00".

Step 2: Activate the rule

Activate the rule so it is evaluated against incoming transactions.

API reference: Activate rule

cURL

curl -X POST "https://tracer.lerian.io/v1/rules/019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "description": "Deny transactions above BRL 10,000 for card payments",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:01:00Z"
}

The rule status changes from DRAFT to ACTIVE.

Rule lifecycle

Status	Behavior
`DRAFT`	Created but not evaluated during validations
`ACTIVE`	Evaluated against every incoming transaction
`INACTIVE`	Paused and excluded from evaluation

INACTIVE rules can transition back to DRAFT for re-editing using POST /v1/rules/{id}/draft.

Step 3: Create a spending limit

Create a spending limit to control transaction amounts by scope and time period. Like rules, limits start in DRAFT status.

API reference: Create limit

cURL

curl -X POST "https://tracer.lerian.io/v1/limits" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Daily Corporate Limit",
   "description": "Daily spending limit for corporate segment",
   "limitType": "DAILY",
   "maxAmount": "50000.00",
   "currency": "BRL",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "transactionType": "CARD"
     }
   ]
 }'

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Corporate Limit",
  "description": "Daily spending limit for corporate segment",
  "limitType": "DAILY",
  "maxAmount": "50000.00",
  "currency": "BRL",
  "scopes": [
    {
      "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetAt": "2026-03-06T00:00:00Z",
  "createdAt": "2026-03-05T10:02:00Z",
  "updatedAt": "2026-03-05T10:02:00Z"
}

Limit types

Type	Reset behavior	Use case
`DAILY`	Resets at midnight UTC	Daily spending caps
`WEEKLY`	Resets weekly	Weekly spending caps
`MONTHLY`	Resets on the 1st of each month	Monthly budget control
`CUSTOM`	Resets after the configured custom period	Fixed campaign or event windows
`PER_TRANSACTION`	No tracking — evaluated per transaction	Per-transaction maximums

Activate the limit the same way you activated the rule:

cURL

curl -X POST "https://tracer.lerian.io/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Step 4: Validate a transaction

Send a transaction to Tracer for real-time validation against all active rules and limits. Tracer does not make external calls during evaluation, so response times stay under 80ms (p99).

API reference: Validate transaction

cURL

curl -X POST "https://tracer.lerian.io/v1/validations" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
   "transactionType": "CARD",
   "subType": "debit",
   "amount": "1500.00",
   "currency": "BRL",
   "transactionTimestamp": "2026-03-05T10:30:00Z",
   "account": {
     "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
     "type": "checking",
     "status": "active"
   },
   "segment": {
     "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
     "name": "corporate"
   },
   "metadata": {
     "channel": "MOBILE_APP"
   }
 }'

{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "validationId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "decision": "ALLOW",
  "reason": "Transaction approved",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b"
  ],
  "limitUsageDetails": [
    {
      "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
      "limitAmount": "50000.00",
      "currentUsage": "1500.00",
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}

Decision types

Decision	Meaning	Your system should
`ALLOW`	All rules passed, all limits within threshold	Proceed with the transaction
`DENY`	A deny rule matched or a limit was exceeded	Block the transaction
`REVIEW`	A review rule matched, no deny rules triggered	Route to manual review

Tracer returns decisions as recommendations. Your system is responsible for acting on the decision (block, approve, or queue the transaction).

Transaction types

Type	Subtypes	Description
`CARD`	debit, credit, prepaid	Card transactions
`WIRE`	domestic, international, ach	Wire transfers
`PIX`	instant, scheduled	Brazilian instant payments
`CRYPTO`	bitcoin, ethereum, stablecoin	Cryptocurrency transactions

Step 5: Check limit usage

Monitor how much of a spending limit has been consumed in the current period.

API reference: Retrieve limit usage

cURL

curl -X GET "https://tracer.lerian.io/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/usage" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "limitAmount": "50000.00",
  "currentUsage": "15000.00",
  "utilizationPercent": 30.0,
  "nearLimit": false,
  "resetAt": "2026-03-06T00:00:00Z"
}

The nearLimit flag activates at 80% utilization, enabling proactive limit management.

Step 6: Review audit events

Every validation decision and configuration change is recorded in an immutable audit log. Query audit events for compliance reporting and debugging.

API reference: List audit events

cURL

curl -X GET "https://tracer.lerian.io/v1/audit-events?eventType=TRANSACTION_VALIDATED&startDate=2026-03-05T00:00:00Z&endDate=2026-03-06T00:00:00Z" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Audit event types

Event type	Description
`TRANSACTION_VALIDATED`	A transaction was validated
`RULE_CREATED`	A new rule was created
`RULE_ACTIVATED`	A rule was activated
`RULE_DEACTIVATED`	A rule was deactivated
`LIMIT_CREATED`	A new limit was created
`LIMIT_ACTIVATED`	A limit was activated
`LIMIT_DEACTIVATED`	A limit was deactivated

Step 7: Verify audit integrity

Verify the cryptographic hash chain of audit events to confirm that no records have been tampered with. This is essential for SOX and GLBA compliance.

API reference: Verify audit event

cURL

curl -X GET "https://tracer.lerian.io/v1/audit-events/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/verify" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "isValid": true,
  "totalChecked": 1234,
  "message": "Hash chain integrity verified successfully"
}

Next steps

Getting started with Tracer

Business overview of the validation lifecycle and core concepts.

Rule engine

Deep dive into CEL expressions and advanced rule configuration.

Spending limits

Configure and manage limits by scope, period, and transaction type.

Error handling

Complete list of error codes and how to resolve them.

Documentation Index

​Before you begin

​Step 1: Create a rule

​Step 2: Activate the rule

​Rule lifecycle

​Step 3: Create a spending limit

​Limit types

​Step 4: Validate a transaction

​Decision types

​Transaction types

​Step 5: Check limit usage

​Step 6: Review audit events

​Audit event types

​Step 7: Verify audit integrity

​Next steps

Getting started with Tracer

Rule engine

Spending limits

Error handling

Before you begin

Step 1: Create a rule

Step 2: Activate the rule

Rule lifecycle

Step 3: Create a spending limit

Limit types

Step 4: Validate a transaction

Decision types

Transaction types

Step 5: Check limit usage

Step 6: Review audit events

Audit event types

Step 7: Verify audit integrity

Next steps