Tracer API quick start

Get Tracer running in minutes: create your first rule and spending limit, validate a transaction, and review the audit trail using the Tracer REST APIs.

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.sandbox.lerian.net 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.sandbox.lerian.net/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.sandbox.lerian.net/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 during validation, on transactions its scope matches
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.sandbox.lerian.net/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	Period counting	Use case
DAILY	A new count starts each calendar day at 00:00 UTC	Daily spending caps
WEEKLY	A new count starts each ISO week, Monday at 00:00 UTC	Weekly spending caps
MONTHLY	A new count starts on the 1st of the month at 00:00 UTC	Monthly budget control
CUSTOM	One count for the whole range	Fixed campaign or event windows
PER_TRANSACTION	No count is kept — each transaction is checked on its own	Per-transaction maximums

Activate the limit the same way you activated the rule:

cURL

curl -X POST "https://tracer.sandbox.lerian.net/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 the rules and limits that apply to it.

API reference: Validate transaction

cURL

curl -X POST "https://tracer.sandbox.lerian.net/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	Example 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

transactionType accepts only the four values above. subType is a free-form string (up to 50 characters, normalized to lowercase) — the subtypes listed are common examples, not a closed list.

Step 5: Check limit usage

---

Review a limit’s cumulative consumption. For the consumption behind a single decision, read limitUsageDetails on the POST /v1/validations response.

API reference: Retrieve limit usage

cURL

curl -X GET "https://tracer.sandbox.lerian.net/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"
}

currentUsage here adds up the usage counters recorded for the limit, across periods and scopes.

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.sandbox.lerian.net/v1/audit-events?event_type=TRANSACTION_VALIDATED&start_date=2026-03-05T00:00:00Z&end_date=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

This table shows the most common event types. For the complete list — including update, delete, draft, and reservation lifecycle events — see Audit and compliance.

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.sandbox.lerian.net/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.