Feeding Transactions into Regulus

Use the Transactions API or our SDK to push on-chain or off-chain transactions into Regulus so they can be evaluated by the rule engine, checked against watchlists, and — when necessary — create alerts for your compliance workflows.

Key Concepts

• Validation: Incoming payloads are validated server-side. Invalid payloads return 400 with a human-readable message.
• Authentication: Hybrid auth is supported — use a Bearer JWT or an x-api-key header.
• Rate limiting: API requests pass through a rate-limiter to protect the service and your org.
• Rule evaluation & watchlist: Transactions are checked against organization-specific rules and watchlists and flagged when matches occur.
• Audit logs: All significant operations (e.g. transaction creation, flagging, rule changes) are logged using the audit logger to support compliance and troubleshooting.
• Notifications: When a transaction is flagged we create alerts and send notifications asynchronously. In addition to in-app notifications, flagged transactions can also be forwarded to external systems via integrations. For more details, see the Integrations documentation.

Sending Transactions via API

You can feed transactions into Regulus through the /transactions endpoints. Refer to the official API documentation for full details on request structure, authentication, and response formats:

Using the SDK

Install theRegulus SDK to start sending transactions and receiving alerts.

npm install @regulus/sdk

Get your API key from the organization dashboard and implement the SDK in your codebase to start sending transaction data for monitoring.

const RegulusSDK = require('regulus-sdk');

const apiKey = process.env.API_KEY; 
const organizationId = process.env.ORGANIZATION_ID;
const sdk = new RegulusSDK(apiKey, organizationId);

const transactionData = {
  transaction_id: "txn_12345",
  user_id: "user_001",
  amount: 1000,
  currency: "USD",
  country: "US",
  timestamp: new Date().toISOString(),
};

What happens after a transaction is received?

1. Validation: The request payload is validated. If invalid, an HTTP 400 with the validation message is returned and the error is logged.
2. Watchlist check: The transaction is checked against organization watchlists (user IDs, countries, etc.).
3. Rule evaluation: Organization rules are fetched and evaluated. The rule engine returns whether the transaction was flagged, along with matched rule details.
4. Persistence: The transaction and flagged metadata are stored in the database inside a single transactional operation.
5. Alerts: If flagged, one or more alert records are created and an audit entry is written describing the action (Transaction Flagged: <txn_id>).
6. Notifications: Notifications are dispatched asynchronously for each matched rule.

Error handling & observability

Errors at every stage (validation, DB, rule evaluation, notification) are logged using the central logger. Critical actions and security-relevant changes are written to the audit logs via logAudit. Typical responses include:

• 400 — validation error (payload malformed)
• 401 — unauthorized (invalid/missing token)
• 403 — forbidden (invalid organization or insufficient permissions)
• 409 — conflict (transaction_id already exists)
• 429 — too many requests (rate limiting)
• 500 — internal server error (logged with stack)

Troubleshooting tips

• If you receive a 409, confirm the transaction_id isn't duplicated — transaction IDs must be unique per organization.
• For validation errors, check types and timestamp format (ISO 8601).
• If alerts are not triggering, verify that your organization has rules configured and that rule fields/operators match the transaction payload keys.
• Check application logs for entries from logger and audit entries from logAudit for details about why a transaction was flagged or why an operation failed.