> ## 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.

# Tracer API quick start

<Tip>
  **This guide is intended for developers.** If you're looking for a business-level overview of what Tracer does, see [What is Tracer?](/en/tracer/what-is-tracer).
</Tip>

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
* A valid API key for authentication

All examples use `cURL`. Replace `$API_KEY` with your API key and `https://tracer.lerian.io` with your Tracer URL.

## 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.

<Tip>
  API reference: [Create rule](/en/reference/tracer/create-rule)
</Tip>

```bash cURL theme={null}
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"
     }
   ]
 }'
```

```json theme={null}
{
  "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.

<Info>
  All monetary values in Tracer are expressed in the smallest currency unit (e.g., centavos for BRL, cents for USD). BRL 10,000.00 = 1,000,000 centavos.
</Info>

## Step 2: Activate the rule

***

Activate the rule so it is evaluated against incoming transactions.

<Tip>
  API reference: [Activate rule](/en/reference/tracer/activate-rule)
</Tip>

```bash cURL theme={null}
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"
```

```json theme={null}
{
  "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.

<Tip>
  API reference: [Create limit](/en/reference/tracer/create-limit)
</Tip>

```bash cURL theme={null}
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": 5000000,
   "currency": "BRL",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "transactionType": "CARD"
     }
   ]
 }'
```

```json theme={null}
{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Corporate Limit",
  "description": "Daily spending limit for corporate segment",
  "limitType": "DAILY",
  "maxAmount": 5000000,
  "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      |
| `MONTHLY`         | Resets on the 1st of each month         | Monthly budget control   |
| `PER_TRANSACTION` | No tracking — evaluated per transaction | Per-transaction maximums |

Activate the limit the same way you activated the rule:

```bash cURL theme={null}
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 are consistently under 100ms.

<Tip>
  API reference: [Validate transaction](/en/reference/tracer/validate-transaction)
</Tip>

```bash cURL theme={null}
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": 150000,
   "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"
   }
 }'
```

```json theme={null}
{
  "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": 5000000,
      "currentUsage": 150000,
      "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       |

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

### 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.

<Tip>
  API reference: [Retrieve limit usage](/en/reference/tracer/retrieve-limit-usage)
</Tip>

```bash cURL theme={null}
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"
```

```json theme={null}
{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "limitAmount": 5000000,
  "currentUsage": 1500000,
  "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.

<Tip>
  API reference: [List audit events](/en/reference/tracer/list-audit-events)
</Tip>

```bash cURL theme={null}
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.

<Tip>
  API reference: [Verify audit event](/en/reference/tracer/verify-audit-event)
</Tip>

```bash cURL theme={null}
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"
```

```json theme={null}
{
  "isValid": true,
  "totalChecked": 1234,
  "message": "Hash chain integrity verified successfully"
}
```

## Next steps

***

<CardGroup cols={2}>
  <Card title="Getting started with Tracer" icon="rocket" href="/en/tracer/getting-started">
    Business overview of the validation lifecycle and core concepts.
  </Card>

  <Card title="Rule engine" icon="gears" href="/en/tracer/rule-engine">
    Deep dive into CEL expressions and advanced rule configuration.
  </Card>

  <Card title="Spending limits" icon="gauge-high" href="/en/tracer/spending-limits">
    Configure and manage limits by scope, period, and transaction type.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/en/reference/tracer/tracer-error-list">
    Complete list of error codes and how to resolve them.
  </Card>
</CardGroup>