AventraGuard Public API

A server-to-server REST API for ingesting transactions and parties, receiving real-time AML risk signals, and reading compliance artifacts — all secured with HMAC-SHA256 signed requests.

Base URLs

There is no separate sandbox host — Staging is the sandbox. Use it with a ak_test_ key to integrate and test against real platform behaviour without touching production data or filing to FINTRAC.

The key prefix and the host must agree — a ak_live_ key on the staging/dev (test) hosts is rejected with HTTP 401, and a ak_test_ key on production is rejected too.

Step 1 — Get credentials

An API key is an opaque string that identifies your reporting entity and grants a set of permissions (scopes). It is issued by an AventraGuard operator — there is no public self-service sign-up.

A webhook secret is a separate credential used only to verify that events we push to your endpoint came from AventraGuard (not an attacker who found your URL).

• 1
  Ask the admin or MLRO on your team to sign in to AventraGuard → Settings → Public API → Keys → Create key. Choose a label (e.g. acme-prod-2026), select scopes, set mode to Live for production or Test for the staging/dev (sandbox) hosts.
• 2
  The raw key is shown once in a modal. Copy it directly into your secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Actions secret, etc.). Once the modal closes, only the hashed form is stored — there is no recovery path.
• 3
  To create a webhook signing secret, go to Settings → Public API → Webhooks → Add webhook. The secret field in the 201 response (or the UI modal) is also shown exactly once. Store it the same way.

Step 2 — Make your first signed request

HMAC (Hash-based Message Authentication Code) is a way of proving you sent a specific request without a password travelling on the wire. You compute a cryptographic fingerprint of the request using your API key as the secret, then send the fingerprint in a header. The server recomputes the fingerprint and compares. If they match, you must have the key.

GET requests only require the X-API-Key header. POST/PATCH/DELETE additionally require X-Aventra-Timestamp and X-Aventra-Signature — details in Authentication & Signing. Here is a GET to get you started:

# Replace the key value with your real key.
curl -sS "https://api.aventraguard.com/v1/parties?limit=5" \
  -H "X-API-Key: ak_live_3f8a9e2b1c0d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f"

import requests

resp = requests.get(
    "https://api.aventraguard.com/v1/parties",
    params={"limit": 5},
    headers={"X-API-Key": "ak_live_..."},
)
resp.raise_for_status()
parties = resp.json()

import aventra "github.com/solvanny/risk-aml-platform/sdk/go"

client, err := aventra.New(
    "https://api.aventraguard.com",
    "ak_live_...",
)
if err != nil { log.Fatal(err) }

parties, err := client.ListParties(ctx, aventra.PartyListParams{Limit: 5})

import { AventraClient } from "@aventraguard/aml-sdk";

const client = new AventraClient(
  "https://api.aventraguard.com",
  "ak_live_...",
);

const parties = await client.listParties({ limit: 5 });

<?php
$ch = curl_init("https://api.aventraguard.com/v1/parties?limit=5");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-API-Key: ak_live_..."],
]);
$parties = json_decode(curl_exec($ch), true);
curl_close($ch);

import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.aventraguard.com/v1/parties?limit=5"))
    .header("X-API-Key", "ak_live_...")
    .GET()
    .build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

Response envelope

Every list endpoint uses the same envelope. A successful call with no data returns {"items":[],"total":0,"limit":5,"next_cursor":""} — expected on a fresh key before you push any data.

Step 3 — Receive your first webhook

A webhook is an HTTP POST that AventraGuard sends to a URL you control whenever something happens — an alert fires, a case opens, a filing is submitted. Instead of polling GET /v1/alerts every few seconds, you register once and we push events to you.

• 1
  Expose a public HTTPS URL (e.g. https://hooks.acme.com/aventraguard). It must resolve to a public IP — loopback and RFC 1918 addresses are rejected.
• 2
  Register it: POST /v1/webhooks with {"url":"https://hooks.acme.com/aventraguard","label":"acme-prod"}. Copy the secret from the 201 response immediately.
• 3
  In your handler, read the raw request body bytes before any JSON parsing, then verify the X-Aventra-Webhook-Signature header. Return HTTP 200 within 15 seconds (offload slow work to a background queue). See Signature verification.

API Keys

An API key identifies your reporting entity and carries a set of scopes. Every request must include it in the X-API-Key header.

Key format

The body is 64 lowercase hex characters (32 bytes of entropy). Total length: 72 characters. We store only the SHA-256 hash — even an operator with full database access cannot recover the raw key.

Scopes

Request the smallest set you need. A missing scope returns 403 insufficient-scope with the required scope name in extensions.required_scope.

Request Signing (HMAC-SHA256)

Signing proves three things at once: you possess the secret, the request was not modified in transit, and (combined with the timestamp) it is not a replay of an old request.

When signing is required

The three headers

String to sign

Construct exactly this string with literal newline (\n) separators. No trailing newline.

METHOD\nPATH_WITH_QUERY\nTIMESTAMP\nBODY_SHA256_HEX

Worked Example

Step-by-step signing of POST /v1/parties with a minimal body. The values below are real — you can verify them against the published test vectors.

#!/usr/bin/env bash
API_KEY="ak_live_3f8a9e2b1c0d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f"
BODY='{"source_party_id":"acme-cust-00001","party_type":"individual"}'
TS=$(date +%s)
PATH_Q="/v1/parties"
BODY_HASH=$(printf "%s" "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
TO_SIGN="POST\n${PATH_Q}\n${TS}\n${BODY_HASH}"
SIG=$(printf "%b" "$TO_SIGN" | openssl dgst -sha256 -hmac "$API_KEY" -hex | awk '{print $2}')

curl -sS https://api.aventraguard.com/v1/parties \
  -H "X-API-Key: $API_KEY" \
  -H "X-Aventra-Timestamp: $TS" \
  -H "X-Aventra-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

import hashlib, hmac, time

def sign(api_key, method, path_q, body):
    ts = str(int(time.time()))
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    to_sign = f"{method}\n{path_q}\n{ts}\n{body_hash}"
    sig = hmac.new(api_key.encode(), to_sign.encode(), hashlib.sha256).hexdigest()
    return ts, sig

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "strconv"
    "time"
)

func sign(apiKey, method, pathQ, body string) (ts, sig string) {
    ts = strconv.FormatInt(time.Now().Unix(), 10)
    h := sha256.Sum256([]byte(body))
    bodyHash := hex.EncodeToString(h[:])
    toSign := fmt.Sprintf("%s\n%s\n%s\n%s", method, pathQ, ts, bodyHash)
    mac := hmac.New(sha256.New, []byte(apiKey))
    mac.Write([]byte(toSign))
    sig = hex.EncodeToString(mac.Sum(nil))
    return
}

import { createHash, createHmac } from "node:crypto";

function sign(apiKey: string, method: string, pathQ: string, body: string) {
  const ts = String(Math.floor(Date.now() / 1000));
  const bodyHash = createHash("sha256").update(body).digest("hex");
  const toSign = `${method}\n${pathQ}\n${ts}\n${bodyHash}`;
  const sig = createHmac("sha256", apiKey).update(toSign).digest("hex");
  return { ts, sig };
}

<?php
function sign(string $apiKey, string $method, string $pathQ, string $body): array {
    $ts = (string) time();
    $bodyHash = hash('sha256', $body);
    $toSign = "$method\n$pathQ\n$ts\n$bodyHash";
    $sig = hash_hmac('sha256', $toSign, $apiKey);
    return [$ts, $sig];
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;

static String[] sign(String apiKey, String method, String pathQ, String body) throws Exception {
    String ts = String.valueOf(Instant.now().getEpochSecond());
    byte[] digest = MessageDigest.getInstance("SHA-256")
        .digest(body.getBytes(StandardCharsets.UTF_8));
    String bodyHash = HexFormat.of().formatHex(digest);
    String toSign = method + "\n" + pathQ + "\n" + ts + "\n" + bodyHash;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(apiKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String sig = HexFormat.of().formatHex(mac.doFinal(toSign.getBytes(StandardCharsets.UTF_8)));
    return new String[]{ ts, sig };
}

Test Vectors

Five precomputed vectors are published at docs/api/test-vectors/hmac-signing-v1.json. Run your signing implementation against these before sending any real request — the server's own test suite regenerates them on every run. Here is the post_party vector:

Common drift causes: lowercase method, including the Host: header in the string, stripping the query string, uppercase hex output.

Idempotency

Idempotency means "doing the same thing twice has the same effect as doing it once." The Idempotency-Key header lets you safely retry a POST or PATCH after a network failure without creating duplicates.

• A UUID v4 is recommended (any unique string up to 128 bytes is accepted).
• Keys are scoped per API key — your key's acme-001 does not collide with another integrator's.
• The first successful 2xx response is cached for 24 hours. Retries with the same key replay the cached response and add Idempotency-Replayed: true.
• Only 2xx responses are cached. A validation error on the first try will not be replayed — the next attempt runs fresh.
• Reusing the same key with a different request body returns 409 idempotency-conflict. Generate a fresh UUID per logical operation.
• Cap your retry horizon below 24 hours for write endpoints — a retry after key expiry will re-execute.

Replay Protection

Two mechanisms prevent replayed requests:

• Timestamp window: X-Aventra-Timestamp must be within 5 minutes of the server clock. Drift returns 401 timestamp-expired. Keep your servers on NTP; always compute the timestamp at request-build time, not at config load time.
• Nonce cache: The server derives nonce = sha256(timestamp + ":" + signature) and stores it for 10 minutes. A repeated (timestamp, signature) pair returns 401 replay-detected. Always re-sign on retry with a fresh timestamp.

Rate Limits

On 429 the server returns a Retry-After header. Sleep that many seconds, then re-sign and retry with the same Idempotency-Key on mutations. Response headers RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset are available on every response to let you pace proactively.

API Reference

Every endpoint, parameter, and response field. Signing column: required = POST/PATCH/DELETE; optional = GET.

Parties

A party is a customer or business entity subject to AML monitoring. Parties are the unit of risk scoring, sanctions screening, and EDD tracking.

curl -sS https://api.aventraguard.com/v1/parties \
  -H "X-API-Key: ak_live_..." \
  -H "X-Aventra-Timestamp: $TS" \
  -H "X-Aventra-Signature: $SIG" \
  -H "Idempotency-Key: party-acme-cust-00001" \
  -H "Content-Type: application/json" \
  -d '{"source_party_id":"acme-cust-00001","party_type":"individual","given_name":"Alex","family_name":"Morgan","address_country":"CA"}'

party, err := client.CreateParty(ctx, aventra.CreatePartyRequest{
    SourcePartyID: "acme-cust-00001",
    PartyType:     "individual",
    GivenName:     "Alex",
    FamilyName:    "Morgan",
    AddressCountry: "CA",
}, aventra.WithIdempotencyKey("party-acme-cust-00001"))

const party = await client.createParty(
  { source_party_id: "acme-cust-00001", party_type: "individual",
    given_name: "Alex", family_name: "Morgan", address_country: "CA" },
  { idempotencyKey: "party-acme-cust-00001" },
);

{
  "id": "10421",
  "source_party_id": "acme-cust-00001",
  "party_type": "individual",
  "risk_tier": "T1",
  "kyc_status": "",
  "address_country": "CA",
  "edd_required": false,
  "created_at": "2026-05-30T14:00:00Z",
  "updated_at": "2026-05-30T14:00:00Z"
}

{
  "items": [{
    "id": 902,
    "party_id": 10421,
    "list_source": "OSFI",
    "entry_name": "ALEKSANDR MORGAN",
    "hit_kind": "sanctions",
    "match_score": 0.94,
    "disposition": "confirmed",
    "first_seen_at": "2026-04-12T16:22:00Z",
    "last_seen_at": "2026-04-13T09:00:00Z"
  }],
  "total": 1
}

Transactions

Push transactions for AML rule evaluation. The 202 response is immediate — screening runs asynchronously.

curl -sS https://api.aventraguard.com/v1/transactions \
  -H "X-API-Key: ak_live_..." \
  -H "X-Aventra-Timestamp: $TS" \
  -H "X-Aventra-Signature: $SIG" \
  -H "Idempotency-Key: tx-acme-2026-05-30-0001" \
  -H "Content-Type: application/json" \
  -d '{"source_transaction_id":"acme-tx-001","source_party_id":"acme-cust-00001","amount":"9850.00","currency":"CAD","status":"completed","method":"e_transfer","action":"transfer","occurred_at":"2026-05-30T13:59:42Z","source_created_at":"2026-05-30T13:59:42Z"}'

resp, err := client.IngestTransaction(ctx, aventra.IngestTransactionRequest{
    SourceTransactionID: "acme-tx-001",
    SourcePartyID:       "acme-cust-00001",
    Amount:              "9850.00",
    Currency:            "CAD",
    Status:              "completed",
    Method:              "e_transfer",
    Action:              "transfer",
    OccurredAt:          "2026-05-30T13:59:42Z",
    SourceCreatedAt:     "2026-05-30T13:59:42Z",
}, aventra.WithIdempotencyKey("tx-acme-2026-05-30-0001"))

const resp = await client.ingestTransaction(
  { source_transaction_id: "acme-tx-001", source_party_id: "acme-cust-00001",
    amount: "9850.00", currency: "CAD", status: "completed",
    method: "e_transfer", action: "transfer",
    occurred_at: "2026-05-30T13:59:42Z", source_created_at: "2026-05-30T13:59:42Z" },
  { idempotencyKey: "tx-acme-2026-05-30-0001" },
);

Screening Hits

Alerts

An alert is an AML risk signal produced by the rule engine, sanctions screening, PEP match, or behavioural model.

Cases

A case is the unit of analyst investigation, opened when an alert is escalated. Read-only in Phase 1.

{
  "id": "1502",
  "party_id": "10421",
  "status": "investigating",
  "alert_count": 3,
  "opened_at": "2026-05-30T14:01:00Z",
  "due_at": "2026-06-29T14:01:00Z",
  "overdue": false
}

Filings

STR (Suspicious Transaction Report) filings are read-only via the API. The submission workflow remains in-platform because FINTRAC submission requires MLRO four-eyes review.

Batches

Batch management endpoints — see also Bulk / Batch Ingest for the full workflow.

Webhooks (management)

Audit Log

Bulk / Batch Ingest

Upload thousands of transactions or parties in a single request for historical backfills or high-volume onboarding.

What is NDJSON?

NDJSON (Newline-Delimited JSON) is simply one complete JSON object per line, lines separated by \n. There is no outer array and no trailing newline. Each line is exactly the same shape as the single-row POST body.

{"source_transaction_id":"tx-001","source_party_id":"cust-001","amount":"500.00","currency":"CAD","status":"completed","method":"eft","action":"deposit","occurred_at":"2026-01-01T10:00:00Z","source_created_at":"2026-01-01T10:00:00Z"}
{"source_transaction_id":"tx-002","source_party_id":"cust-002","amount":"1200.00","currency":"CAD","status":"completed","method":"wire","action":"transfer","occurred_at":"2026-01-01T11:00:00Z","source_created_at":"2026-01-01T11:00:00Z"}

• Maximum body size: 4 MiB per request. Split larger backfills across multiple batches.
• Invalid rows do not abort the batch — they are recorded as failed with a reason while valid rows proceed.
• Blank lines are ignored.
• Content-Type must be application/x-ndjson.

Async 202 flow

The server validates each line, enqueues valid rows for asynchronous processing, and returns 202 immediately with a batch_id. A 202 is not confirmation every row landed.

curl -sS -X POST https://api.aventraguard.com/v1/transactions/batch \
  -H "X-API-Key: ak_live_..." \
  -H "X-Aventra-Timestamp: $TS" \
  -H "X-Aventra-Signature: $SIG" \
  -H "Idempotency-Key: backfill-2026-q1-001" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @transactions.ndjson

batch, err := client.IngestTransactionsBatch(ctx, items,
    aventra.WithIdempotencyKey("backfill-2026-q1-001"))
// batch.BatchID, batch.StatusURL

const batch = await client.ingestTransactionsBatch(
  items,
  { idempotencyKey: "backfill-2026-q1-001" },
);
// batch.batchId, batch.statusUrl

202 response:

{
  "batch_id": "0193b6d4-9999-7a00-bf01-aaaabbbbcccc",
  "status_url": "/v1/batches/0193b6d4-9999-7a00-bf01-aaaabbbbcccc",
  "state": "accepted",
  "total_rows": 4821
}

Tracking status

Poll GET /v1/batches/{id} or subscribe to the batch.completed webhook. State progresses: accepted → processing → completed.

status, err := client.GetBatch(ctx, batch.BatchID)
if status.FailedRows > 0 {
    errs, _ := client.ListBatchErrors(ctx, batch.BatchID, aventra.BatchErrorsParams{})
    // errs.Items: [{Line:17, Message:"currency: must be ISO 4217"}, ...]
}

const status = await client.getBatch(batch.batchId);
if (status.failedRows > 0) {
  const errs = await client.listBatchErrors(batch.batchId);
  // errs.items: [{ line: 17, message: "currency: must be ISO 4217" }]
}

Cancelling a batch

Stop processing the unprocessed remainder of a batch — e.g. a backfill submitted in error. Already-ingested rows stay ingested. Idempotent for already-cancelled batches. Returns 409 if the batch is already completed (its work is done).

status, err := client.CancelBatch(ctx, batch.BatchID, "wrong source file")

const status = await client.cancelBatch(batch.batchId, "wrong source file");

For parties, use POST /v1/parties/batch / client.IngestPartiesBatch / client.ingestPartiesBatch — identical shape and flow.

Webhooks

AventraGuard pushes events to your HTTPS endpoint the moment they happen — no polling required.

What is a webhook?

A webhook is an HTTP POST we send to a URL you control whenever something noteworthy happens — an alert fires, a case opens, a screening hit is confirmed. You give us a URL; we call it with a JSON payload. You return HTTP 200 to acknowledge, and we move on. If you return anything else, we retry on an exponential curve.

The key difference from polling: instead of asking "did anything happen?" every few seconds, you register once and we tell you immediately. This reduces latency and API load for both sides.

Event catalogue

Payload envelope

{
  "event_id": "0193b6d4-9999-7a00-bf01-aaaabbbbcccc",
  "event_type": "alert.created",
  "created_at": "2026-05-30T14:00:01Z",
  "data": {
    "alert_id": "33010",
    "re_id": "0193b6a8-1e1a-7c00-9d77-3f0a2b1c4d5e",
    "severity": "high",
    "status": "open",
    "rule_code": "STRUCTURED_DEPOSITS",
    "party_id": "10421"
  }
}

event_id is a UUID v7 that is stable across all retry attempts — use it as your idempotency key in your handler. created_at is the event creation time, not the delivery time.

Signature verification

You must verify every webhook before acting on its contents. An attacker who finds your URL could otherwise replay forged events.

The signature header

X-Aventra-Webhook-Signature: t=1748613602,v1=7c1a9b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9fa1b2

• t — Unix timestamp (seconds) of the event creation time. Stable across retries.
• v1 — hex(HMAC-SHA256(raw_secret, "<t>.<raw_body_bytes>")). The signed message binds the timestamp to the body.

During secret rotation the header carries two v1= values. Accept the delivery if any matches your stored secret.

Step-by-step verification

1. Read the raw request body bytes before any JSON parsing. Re-serialising the parsed JSON breaks the hash.
2. Parse X-Aventra-Webhook-Signature: split on ,, extract t= (integer) and all v1= values.
3. Build the signed message: signed_msg = "<t>" + "." + raw_body_bytes.
4. Compute expected = hex(HMAC-SHA256(raw_secret_utf8, signed_msg)).
5. Compare expected to each v1= value in constant time. Accept if any matches.
6. Optionally reject if abs(now - t) > 300 (5-minute clock skew tolerance).
7. Use event_id as your idempotency key — deduplicate before processing.

import aventra "github.com/solvanny/risk-aml-platform/sdk/go"

func receiveWebhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(http.MaxBytesReader(w, r.Body, 4<<20))
    err := aventra.VerifyWebhook(
        []byte("whsec_..."),                      // raw secret as UTF-8
        r.Header.Get("X-Aventra-Webhook-Signature"),
        body,
        5*time.Minute,                          // tolerance
    )
    if errors.Is(err, aventra.ErrSignatureMismatch) {
        http.Error(w, "bad signature", http.StatusUnauthorized)
        return
    }
    // Use event_id as idempotency key, then process
    w.WriteHeader(http.StatusOK)
}

import { verifyWebhook, SignatureMismatchError } from "@aventraguard/aml-sdk";

app.post("/webhooks/aventra", express.raw({ type: "*/*" }), (req, res) => {
  try {
    verifyWebhook(
      process.env.AVENTRA_WEBHOOK_SECRET,            // "whsec_..."
      req.headers["x-aventra-webhook-signature"],
      req.body,           // raw Buffer — before JSON.parse()
      300,                // 5-minute tolerance
    );
  } catch (err) {
    if (err instanceof SignatureMismatchError)
      return res.status(401).end();
    throw err;
  }
  const event = JSON.parse(req.body.toString());
  // dedupe on event.event_id, then process
  res.status(200).end();
});

header  = request.headers["X-Aventra-Webhook-Signature"]
parts   = split(header, ",")
t       = integer value of the "t=" part
v1s     = all "v1=" values (may be 2 during rotation)
msg     = encode_utf8(t + ".") + raw_body_bytes
expected = hex(HMAC-SHA256(raw_secret_utf8, msg))
valid   = ANY(constant_time_equal(expected, v) for v in v1s)
        AND (optional) abs(now() - t) < 300
if !valid: return HTTP 401

Secret rotation

Zero-downtime rotation replaces the signing secret without dropping deliveries. During the overlap window (default 14 days) AventraGuard signs every delivery with both secrets:

X-Aventra-Webhook-Signature: t=1748613602,v1=<sig_old>,v1=<sig_new>

Your verification code already handles this if you iterate all v1= values. No code change needed — just update your stored secret and the overlap window covers the rest.

Endpoints: POST /api/admin/public-api/webhooks/{id}/rotate-secret and POST /api/admin/public-api/webhooks/{id}/finalize-secret-rotation. Both require admin/super_user + TOTP.

Retries & dead-letter

AventraGuard retries a failed delivery 6 more times (7 total attempts) on a graduated curve:

After all 7 attempts fail the delivery is marked dead_lettered. The operator can manually re-trigger from the admin UI. Per-delivery timeout: 15 seconds. HTTP 4xx permanent failures (400, 401, 403, 404, 405, 410, 415, 422) skip the retry curve and go straight to dead-letter.

Each delivery includes X-AM-Delivery-Attempt: <n> (1-indexed) for logging.

Tipping-off / PII — PCMLTFA s.66

Receiver checklist

• Receiver is HTTPS and resolves to a public IP.
• Verifies X-Aventra-Webhook-Signature on every request; returns 401 on mismatch.
• Deduplicates by event_id (idempotent handler).
• Returns 200 within 15 seconds; defers slow work to a background queue.
• Returns 5xx on transient failures (so retries help); 4xx only on permanent errors.
• Logs event_id, event_type, X-AM-Delivery-Attempt, and processing status.
• Webhook secret is stored in a secrets manager, not source control.
• Error responses do not echo back request fields — avoids PII in the delivery log.

Errors

Every error from the AventraGuard API follows RFC 7807 (Problem Details for HTTP APIs) so you only need one parser for your whole integration.

Error shape

{
  "type": "https://aventra.io/errors/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields did not pass validation.",
  "instance": "/v1/transactions",
  "extensions": {
    "fields": [
      { "field": "currency", "message": "must be a valid ISO 4217 code" }
    ]
  }
}

Switch on type, not title or detail — type is part of the contract; title/detail are wording we may refine. The type URI last segment is the stable code string.

All error codes

409 Idempotency conflict

You reused an Idempotency-Key for a logically different operation. The first response was cached and replaying it would be wrong for the new body. Fix: generate a fresh UUID per logical operation. The pattern aventra:tx:<your-tx-id> (deterministic from your source ID) is safe and convenient.

429 Rate limit & Retry-After

HTTP/1.1 429 Too Many Requests
Retry-After: 60
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 1748534460

{
  "type": "https://aventra.io/errors/rate-limit-exceeded",
  "status": 429,
  "extensions": { "retry_after_seconds": 60 }
}

Go SDK

Official Go client — stdlib only, zero third-party dependencies, concurrent-safe.

Install

go get github.com/solvanny/risk-aml-platform/sdk/go

Requires Go 1.25+.

Quick start

• 1
  Import the package as aventra.
• 2
  Call aventra.New(baseURL, apiKey, opts...). The API key is the HMAC signing key — no separate signing secret.
• 3
  Call methods on the returned *Client. Every method accepts a context.Context as first argument.
• 4
  For write methods, supply aventra.WithIdempotencyKey("your-id") to enable safe retries and server-side deduplication.

import (
    aventra "github.com/solvanny/risk-aml-platform/sdk/go"
    "context"
    "time"
)

client, err := aventra.New(
    "https://api.aventraguard.com",
    "ak_live_...",
    aventra.WithTimeout(10*time.Second),
    aventra.WithRetry(aventra.DefaultRetryPolicy),
)

party, err := client.CreateParty(ctx, aventra.CreatePartyRequest{
    SourcePartyID: "cust-001",
    PartyType:     "individual",
}, aventra.WithIdempotencyKey("cust-001"))

All methods

Webhook verification

err := aventra.VerifyWebhook(
    []byte("whsec_3f8a9e2b..."),              // raw secret UTF-8 bytes
    r.Header.Get("X-Aventra-Webhook-Signature"),
    body,                                  // raw bytes before JSON parse
    5*time.Minute,
)
switch {
case errors.Is(err, aventra.ErrSignatureMismatch):
    // reject
case errors.Is(err, aventra.ErrTimestampOutOfTolerance):
    // reject stale delivery
case errors.Is(err, aventra.ErrMalformedSignature):
    // reject malformed header
}

Error handling

var apiErr *aventra.APIError
if errors.As(err, &apiErr) {
    switch apiErr.Type {
    case "https://aventra.io/errors/not-found":
        // 404
    case "https://aventra.io/errors/rate-limit-exceeded":
        retryAfter := apiErr.Extensions["retry_after_seconds"]
    case "https://aventra.io/errors/validation-error":
        fields := apiErr.Extensions["fields"]
    }
}

Retry policy

Retry is off by default. Enable with WithRetry(aventra.DefaultRetryPolicy) — 3 total attempts, 1 s base delay, 30 s cap, 429 and 5xx only. POST/PATCH/DELETE requests without an Idempotency-Key are never retried (unsafe). The SDK re-signs with a fresh timestamp on each retry, satisfying the server's replay-protection requirement.

// Run tests:
go test -count=1 -race ./...

TypeScript SDK

Official TypeScript/Node client — stdlib only, zero third-party runtime dependencies, Node 18+.

Install

npm install @aventraguard/aml-sdk

Requires Node 18+ (uses global fetch and node:crypto).

Quick start

• 1
  Import AventraClient from "@aventraguard/aml-sdk".
• 2
  Construct: new AventraClient(baseURL, apiKey, options). The API key is the HMAC signing key — no separate secret.
• 3
  Await any method. All methods are async and return typed results.
• 4
  For writes, pass { idempotencyKey: "your-id" } as the last argument to enable safe retries.

import { AventraClient, DEFAULT_RETRY_POLICY } from "@aventraguard/aml-sdk";

const client = new AventraClient(
  "https://api.aventraguard.com",
  "ak_live_...",
  { retry: DEFAULT_RETRY_POLICY },
);

const result = await client.ingestTransaction(
  {
    source_transaction_id: "tx-001",
    source_party_id:       "cust-001",
    amount:                "1500.00",
    currency:              "CAD",
    status:                "completed",
    method:                "e_transfer",
    action:                "transfer",
    occurred_at:           new Date().toISOString(),
    source_created_at:     new Date().toISOString(),
  },
  { idempotencyKey: "tx-001" },
);

All methods

Webhook verification

import { verifyWebhook, SignatureMismatchError, MalformedSignatureError } from "@aventraguard/aml-sdk";

// In Express: use express.raw({ type: "*/*" }) to get raw Buffer
app.post("/webhooks/aventra", express.raw({ type: "*/*" }), (req, res) => {
  try {
    verifyWebhook(
      process.env.AVENTRA_WEBHOOK_SECRET,
      req.headers["x-aventra-webhook-signature"] as string,
      req.body as Buffer,
      300,
    );
  } catch (err) {
    if (err instanceof SignatureMismatchError || err instanceof MalformedSignatureError)
      return res.status(401).end();
    throw err;
  }
  const event = JSON.parse((req.body as Buffer).toString());
  // dedupe on event.event_id, then process
  res.status(200).end();
});

Error handling

import { ApiError } from "@aventraguard/aml-sdk";

try {
  await client.getTransaction("missing-id");
} catch (err) {
  if (err instanceof ApiError) {
    switch (err.type) {
      case "https://aventra.io/errors/not-found": break;
      case "https://aventra.io/errors/rate-limit-exceeded":
        console.log(err.extensions?.retry_after_seconds); break;
      case "https://aventra.io/errors/validation-error":
        console.log(err.extensions?.fields); break;
    }
    // err.status is always the real HTTP status
  }
}

Retry policy

Retry is off by default. Enable with retry: DEFAULT_RETRY_POLICY — 3 total attempts, 1 s base delay, 30 s cap, 429 and 5xx only. POST/PATCH/DELETE without idempotencyKey are never retried. The SDK re-signs on each retry. Pass an AbortSignal in CallOptions for per-request cancellation.

Security properties: HTTPS enforced (loopback excepted for local dev); redirects are blocked (redirect: "manual"); all v1= comparisons use timingSafeEqual; success responses bounded to 4 MiB.

# Run tests:
npm run build && npm test

Reference

Rate limits

Response headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (IETF draft form) plus X-RateLimit-* aliases. Limits are tunable by the operator via environment variables.

Idempotency semantics

• Header: Idempotency-Key: <up to 128 bytes>
• Cache duration: 24 hours from first 2xx response.
• Scope: per API key (not global).
• Replay adds: Idempotency-Replayed: true response header.
• Reusing a key with a different body: 409 idempotency-conflict.
• Non-2xx first responses are not cached — the second attempt runs fresh.

Scopes

* Batch lifecycle endpoints require the batch's own resource scope (transactions or parties).

Changelog summary

Full changelog: docs/api/changelog.md in the repository. Breaking changes always ship as a new URL prefix (/v2/); the /v1/ contract is never silently broken.