Getting Started

This guide will help you get up and running with the Link Tracker API quickly and efficiently.

Prerequisites

Basic knowledge of REST APIs and message queues
For real-time streaming: ActiveMQ/STOMP client setup
HTTPS-enabled endpoints for production
Note: Authentication is handled by the Link Dashboard

Authentication

Link Tracker is designed to be accessed through the Link Dashboard, which handles authentication.

Production Architecture:

User/Client
    ↓ (authenticates)
Link Dashboard (Next.js)
    ↓ (validates session)
Auth Server/BFF (Port 4000)
    ↓ (proxies authenticated requests)
Link Tracker Service (Port 3000)

Authentication Flow:

Users authenticate with the Link Dashboard
Auth Server validates JWT tokens and session cookies
Authenticated requests are forwarded to Link Tracker via /api/activity-logs
Link Tracker processes the request (no auth check at service level)
Response flows back through the chain

Direct Service Access (Development Only):

Local development: http://localhost:3000 (no authentication)
Ensure network isolation in development/test environments
Production deployments should only allow access through Auth Server

Base URLs

Link Tracker is available at the following base URLs:

Production API: https://api.ledgerlink.ai/v1
Sandbox API: https://sandbox-api.ledgerlink.ai/v1
Local Development: http://localhost:3000 (default port)

Note: The tracker service runs on port 3000 by default in development.

Making Your First Request

Get Log Messages

Retrieve recent activity logs from the system:

curl -X GET "https://api.ledgerlink.ai/v1/log-messages?limit=10&offset=0" \
  -H "X-API-KEY: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Response:

{
  "data": [
    {
      "_id": "674e1a2b3c4d5e6f7890abcd",
      "timestamp": "2025-11-20T17:00:00.000Z",
      "service": "LinkCore",
      "request_id": "req_67890",
      "event_type": "TRANSACTION_RECEIVED",
      "status": "SUCCESS",
      "metadata": {
        "transaction_id": "tx_abc123",
        "participant_id": "part_456",
        "amount": "1000.00",
        "currency": "USD",
        "type": "DEPOSIT"
      }
    }
  ],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 1547
  }
}

Filter by Service

Query logs from a specific service (case-insensitive regex search):

curl -X GET "https://api.ledgerlink.ai/v1/log-messages?service=LinkCore&limit=20" \
  -H "X-API-KEY: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Filter by Date Range

Retrieve logs within a specific time period:

curl -X GET "https://api.ledgerlink.ai/v1/log-messages?startDate=2025-11-01T00:00:00Z&endDate=2025-11-20T23:59:59Z" \
  -H "X-API-KEY: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Filter by Event Type and Status

Query specific events with status filtering:

curl -X GET "https://api.ledgerlink.ai/v1/log-messages?type=TRANSACTION_RECEIVED&status=SUCCESS&sortBy=timestamp&sortOrder=desc" \
  -H "X-API-KEY: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Request Parameters

Common Query Parameters

offset (integer, optional): Page number for pagination (default: 0)
limit (integer, optional): Number of records per page (default: 20, max: 100)
sortBy (string, optional): Field to sort by (e.g., "timestamp", "service")
sortOrder (string, optional): Sort direction ("asc" or "desc", default: "desc")

Filtering Parameters

service (string, optional): Filter by service name (case-insensitive regex match)
requestId (string, optional): Filter by request ID (case-insensitive regex match)
startDate (string, optional): Filter logs after this date (ISO 8601 format)
endDate (string, optional): Filter logs before this date (ISO 8601 format) - Note: Both startDate and endDate must be provided together
type (string, optional): Filter by event type (see Event Types)
status (string, optional): Filter by status: "SUCCESS", "FAILED", "ERROR", "PENDING", "BLOCKED", "WARNING"

Event Types

Link Tracker supports a comprehensive list of event types. Here are some common ones:

Transaction Events:

TRANSACTION_RECEIVED, TRANSACTION_RECEIVED_FROM_CORE
TRANSACTION_STATUS_CHANGED, TRANSACTION_PHASE_CHANGED
TRANSACTION_VALUED, TRANSACTION_BLOCKED, TRANSACTION_PASSED
TRANSACTION_SENT_TO_INSTITUTION, TRANSACTION_PROCESSING_ERROR
TRANSACTION_REPORT, DUPLICATE_TRANSACTION, INVALID_TRANSACTION

Participant & Account Events:

PARTICIPANT_CREATED, PARTICIPANT_DELETED, PARTICIPANT_NOT_FOUND
ACCOUNT_CREATED, ACCOUNT_DELETED, ACCOUNT_CREATION_ERROR
ACCOUNT_BALANCE_INQUIRY_SUCCESS, ACCOUNT_BALANCE_INQUIRY_ERROR
OMNIBUS_ACCOUNT_CREATED, FEE_PAYER_ACCOUNT_CREATED

System & Application Events:

APPLICATION_STARTED, APPLICATION_STOPPED, APPLICATION_READY
APPLICATION_EVENT, ERROR

Valuation Events:

VALUATION_REQUESTED, VALUATION_PROCESSED

Other Events:

LEDGER_UPDATE_INITIATED, LEDGER_UPDATE_COMPLETED
EXTERNAL_INSTITUTION_CUSTOMER_VERIFIED
CCTP_SWAP_INITIATED, CCTP_SWAP_INITIATION_FAILED
DAILY_REPORT, ASSET_NOT_FOUND

For the complete list, see the API Reference.

Response Format

All API responses follow a consistent format:

Success Response

{
  "data": [...],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 1547
  }
}

Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid query parameter: sortBy",
    "details": [
      {
        "field": "sortBy",
        "message": "Must be one of: timestamp, service, status"
      }
    ],
    "requestId": "req_123456789",
    "timestamp": "2025-11-20T17:00:00.000Z"
  }
}

Real-time Event Streaming

Link Tracker uses ActiveMQ/STOMP for real-time event streaming. Services can publish log messages directly to the message queue.

Message Pattern

Internal services use the add_log_message message pattern to publish logs:

// Example: Publishing a log message via ActiveMQ
{
  pattern: 'add_log_message',
  data: {
    timestamp: new Date(),
    service: 'YourService',
    request_id: 'req_123456',
    event_type: 'TRANSACTION_RECEIVED',
    status: 'SUCCESS',
    metadata: {
      transaction_id: 'tx_abc',
      amount: '1000.00'
    }
  }
}

Test Endpoint

Use the test endpoint to verify ActiveMQ connectivity:

curl -X POST "https://api.ledgerlink.ai/v1/log-messages/test-add-log-message" \
  -H "X-API-KEY: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

This publishes a sample valuation event to the message queue.

Local Development Setup

To run Link Tracker locally:

# Install Node.js version manager and correct Node version
nvm install
nvm use

# Start MongoDB and ActiveMQ with Docker
yarn dev:provision:db

# Install dependencies
yarn install

# Configure environment
cd server
cp .env.example .env
# Edit .env with your configuration

# Start the server
yarn dev:server:start

The API will be available at http://localhost:3000 with Swagger documentation at http://localhost:3000/api.

Sandbox Environment

Test your integration safely using our sandbox environment:

Sandbox URL: https://sandbox-api.ledgerlink.ai/v1
Identical to production APIs
Test data and scenarios
No real transactions
MongoDB and ActiveMQ test instances

Next Steps

API Reference - Explore all available endpoints
Error Handling - Learn about error codes and recovery
FAQ - Find answers to common questions

Need Help? Contact helpdesk@ledgerlink.ai

Prerequisites​

Authentication​

Base URLs​

Making Your First Request​

Get Log Messages​

Filter by Service​

Filter by Date Range​

Filter by Event Type and Status​

Request Parameters​

Common Query Parameters​

Filtering Parameters​

Event Types​

Response Format​

Success Response​

Error Response​

Real-time Event Streaming​

Message Pattern​

Test Endpoint​

Local Development Setup​

Sandbox Environment​

Next Steps​