Tracer API quick start

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

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

This guide takes you 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 or $JWT with your Bearer token, and https://tracer.sandbox.lerian.net with your Tracer URL.

Auth mode depends on deployment. A self-hosted deployment with an API key uses X-API-Key. On Lerian Cloud, use Authorization: Bearer $JWT, which Access Manager issues with the tenantId claim, and replace every -H "X-API-Key: $API_KEY" in this guide with -H "Authorization: Bearer $JWT". Tracer resolves the tenant from the token automatically, so never pass the tenant identifier in any other field.

Step 1: Create a rule

---

Create a validation rule with a CEL expression. Every new rule starts 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",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "scheme": "CARD"
     }
   ]
 }'

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD",
      "scheme": "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) appear as decimal strings, for example "1500.00" or "10000.00".

Step 2: Activate the rule

---

Activate the rule. Tracer then evaluates it 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",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD",
      "scheme": "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. The optional resetTime starts each period at a UTC time of day. The example starts each day at 03:00 UTC.

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",
   "asset": "BRL",
   "resetTime": "03:00",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "scheme": "CARD"
     }
   ]
 }'

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Corporate Limit",
  "description": "Daily spending limit for corporate segment",
  "limitType": "DAILY",
  "maxAmount": "50000.00",
  "asset": "BRL",
  "scopes": [
    {
      "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
      "transactionType": "CARD",
      "scheme": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetTime": "03:00",
  "resetAt": "2026-03-06T03: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 day at the reset time (00:00 UTC by default)	Daily spending caps
WEEKLY	A new count starts each Monday at the reset time (00:00 UTC by default)	Weekly spending caps
MONTHLY	A new count starts on the 1st of the month at the reset time (00:00 UTC by default)	Monthly budget control
CUSTOM	One count for the whole range	Fixed campaign or event windows
PER_TRANSACTION	Tracer keeps no count and checks each transaction 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.

To decide by rules alone, without checking or counting any limit, send the same request to POST /v1/validations/rules-only. See Rules-only validation.

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",
   "scheme": "CARD",
   "subType": "debit",
   "amount": "1500.00",
   "asset": "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",
  "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, or a rule expression failed for the request	Route to manual review

Tracer returns decisions as recommendations. Your system must act on the decision (block, approve, or queue the transaction).

Payment schemes

Scheme	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

scheme takes 1 to 50 characters from A-Z, 0-9, _ and -, after Tracer trims the value and converts it to upper case. The four values above are examples, not a closed list. transactionType is the deprecated name of scheme. A validation request must carry one of the two. If you send both, they must carry the same value, or Tracer returns 0540. 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

---

Read how much of a limit the current period has consumed. 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
}

currentUsage here covers the current period of the limit, for the scope that consumed the most. It includes the capacity that unconfirmed Midaz ledger reservations hold.

Step 6: Review audit events

---

Tracer records validation decisions and configuration changes 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.

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

Detailed guide to CEL expressions and advanced rule configuration.

Spending limits

Configure and manage limits by scope, period, and payment scheme.

Error handling

Complete list of error codes and how to resolve them.