Broker Integration API Specification

1. Overview

Artham is a marketplace platform that connects fund managers (Investment Advisors registered with SEBI) with clients through distribution partners. As part of this integration, Artham's servers call your (the broker's) APIs — to fetch client information, and to push executed trades to a receiver you host. One endpoint runs the other way round: Artham hosts it, and you call it once a day to pull your clients' holdings.

How It Works

1. Artham calls your APIs — you build the endpoints described in this document.
2. You verify our identity — using the API key + HMAC signature we send with every request.
3. You return JSON responses — in the standard format described below.
4. You call one Artham API — API 3, the daily holdings pull. Artham hosts it and you are the caller, so the roles above are reversed: you sign the request, we verify it and return the JSON.

API Summary

Base URLs

Two of the three endpoints live on your servers; API 3 lives on ours.

Hosted by you

You provide these to Artham. The API 1 path is appended to your base URL; the API 2 receiver is a full URL of your choosing.

Production:  https://api.yourbroker.com
Sandbox:     https://sandbox-api.yourbroker.com

Hosted by Artham

The API 3 path is appended to the base URL for the environment you are calling.

Production:  https://api.artham.co
Sandbox:     https://distributor-api.artham.co

2. Authentication

The whole integration uses one authentication scheme, in both directions. Every request carries two headers — Artham sends them on API 1 and API 2; you send them on API 3:

Credential Setup

1. Artham generates an API Key (public identifier) and a Shared Secret (private, used for HMAC) for each broker.
2. Artham will share both credentials with you over email.
3. You store the API Key and Shared Secret on your server. Use them to verify the requests Artham sends you (API 1, API 2), and to sign the requests you send Artham (API 3).

Signature Computation

The signature is computed the same way by whichever side is calling:

message = "{HTTP_METHOD}\n{path}\n{body}"

signature = HMAC-SHA256(key: SHARED_SECRET, message: message)
            → output as lowercase hex string

Verifying — Artham → You

1. Check API key — look up the X-Api-Key header value. Reject with 401 if it doesn't match the key Artham shared with you.
2. Recompute signature — using the Shared Secret, compute the HMAC-SHA256 of the same message format shown above.
3. Compare — use a constant-time comparison. Reject with 401 if signatures don't match.

Signing — You → Artham

1. Build the message — "{METHOD}\n{path}\n{body}", exactly as above. API 3 is a GET with no body, so the message is "GET\n/api/v1/broker/holdings\n".
2. Compute the HMAC — HMAC-SHA256 of that message with your Shared Secret, as a lowercase hex string.
3. Send both headers — X-Api-Key (your key, unchanged) and X-Signature (the hex digest). Artham runs the same three verification steps in reverse and answers 401 if either fails.

See Section 7 for complete code in Python, Java, and C#. The computation is identical whether you are verifying or signing.

3. Error Handling

Response Envelope

All responses must follow this structure. The APIs you build must use it, and Artham's own API 3 response uses it too — so a single parser handles every response in this document.

Success

{
  "success": true,
  "data": { ... },
  "error": null
}

Error

{
  "success": false,
  "data": null,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "No client found with code AB9999."
  }
}

HTTP Status Codes

Error Codes

Use these standard error codes in the error.code field:

4. API 1 — Get Client Details Required

This is the primary API. Artham calls this to fetch a client's KYC information, personal details, and bank account details when a client is being onboarded onto the advisory platform.

{
  "success": true,
  "data": {
    "clientCode": "AB1234",
    "rmCode": "RM001",
    "name": "Rajesh Kumar",
    "pan": "ABCDE1234F",
    "dateOfBirth": "1990-05-15",
    "address1": "123 MG Road",
    "address2": "Andheri West",
    "address3": "",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pinCode": "400058",
    "emailAddress": "rajesh@example.com",
    "mobileNumber": "9876543210",
    "accountNo": "1234567890",
    "ifscCode": "HDFC0001234",
    "accountType": "S",
    "clientTypeCode": 1,
    "isNRI": false,
    "isPoliticallyExposedPerson": false
  },
  "error": null
}

5. API 2 — Executed Trades Push Required

After a dealer uploads the end-of-day trade file, Artham pushes that broker's executed trades (fills) to a receiver endpoint that you host. This is an event-driven push — Artham is the caller. There is no date parameter and no polling; each record carries its own timestamp.

{
  "trades": [
    {
      "clientCode": "AB1234",
      "exchange": "NSE",
      "segment": "CM",
      "scripName": "TCS",
      "transactionType": "BUY",
      "isin": "INE467B01029",
      "quantity": "10",
      "price": "3450.50",
      "productType": "Delivery",
      "orderType": "Limit",
      "exchangeOrderNumber": "1100000012345678",
      "timestamp": "27 FEB 2026 14:36:49"
    }
  ]
}

{
  "status": true,
  "code": 200,
  "message": "Trades received successfully"
}

6. API 3 — Client Holdings Snapshot Required

A once-a-day snapshot of the equity holdings and cash balances of every client mapped to your brokerage on Artham, returned in a single response. It exists so you can store the advisory-side position of your clients in your own database and reconcile it against your books.

message   = "GET\n/api/v1/broker/holdings\n"

signature = HMAC-SHA256(key: SHARED_SECRET, message: message)
            → lowercase hex

secret     = "artham_demo_secret_9f2b7c41e8d3"
message    = "GET\n/api/v1/broker/holdings\n"
signature  = e1ed253a76977a84da1ff548a51db899426044fe2c0c62c6adc911b73204584a

curl -X GET "https://distributor-api.artham.co/api/v1/broker/holdings" \
  -H "X-Api-Key: <your API key>" \
  -H "X-Signature: <64-char lowercase hex>"

{
  "success": true,
  "error": null,
  "data": {
    "asOf": "2026-09-01",
    "clientCount": 128,
    "holdingCount": 1043,
    "cashCount": 121,
    "holdings": [
      { "clientCode": "AR001234", "isin": "INE002A01018", "symbol": "RELIANCE", "exchange": "NSE", "quantity": "25.0000" },
      { "clientCode": "AR001234", "isin": "INE467B01029", "symbol": "TCS",      "exchange": "NSE", "quantity": "8.0000"  },
      { "clientCode": "AR005678", "isin": "INE009A01021", "symbol": "INFY",     "exchange": "NSE", "quantity": "40.0000" },
      { "clientCode": "AR005678", "isin": "INE002A01018", "symbol": "500325",   "exchange": "BSE", "quantity": "10.0000" }
    ],
    "cash": [
      { "clientCode": "AR001234", "amount": "10018.67" },
      { "clientCode": "AR005678", "amount": "205.02"   }
    ]
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_TOKEN_INVALID",
    "message": "Invalid API key or signature."
  }
}

7. Signature — Code Samples

Complete examples for both halves of the integration, in each supported stack. The first group verifies the signature on requests Artham sends you (API 1, API 2). The second group signs and sends your daily API 3 call.

Python — Verifying (API 1 & 2)

import hmac
import hashlib

def verify_signature(shared_secret, method, path, body, received_signature):
    """
    Verify the HMAC-SHA256 signature sent by Artham.

    Args:
        shared_secret: The secret shared by Artham for your broker
        method: HTTP method, e.g. "GET"
        path: Request path, e.g. "/api/v1/clients/PP001/AB1234"
        body: Raw request body as string ("" for GET requests)
        received_signature: The X-Signature header value

    Returns:
        True if signature is valid
    """
    message = f"{method}\n{path}\n{body}"

    expected = hmac.new(
        shared_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison to prevent timing attacks
    return hmac.compare_digest(expected, received_signature)


# ─── Example: Flask middleware ───────────────────────────────
from flask import request, abort

# The credentials Artham shared with you
ARTHAM_API_KEY = "artham_live_k8Fj2mNp..."
ARTHAM_SHARED_SECRET = "your_shared_secret_here"

@app.before_request
def check_artham_signature():
    api_key = request.headers.get('X-Api-Key')
    signature = request.headers.get('X-Signature')

    if not api_key or not signature:
        abort(401, 'Missing authentication headers')

    if api_key != ARTHAM_API_KEY:
        abort(401, 'Unknown API key')

    body = request.get_data(as_text=True) or ""

    if not verify_signature(
        ARTHAM_SHARED_SECRET,
        request.method, request.path, body, signature
    ):
        abort(401, 'Invalid signature')

Java — Verifying (API 1 & 2)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

public class ArthamSignatureVerifier {

    /**
     * Verify the HMAC-SHA256 signature sent by Artham.
     *
     * @param sharedSecret  The secret shared by Artham for your broker
     * @param method        HTTP method, e.g. "GET"
     * @param path          Request path, e.g. "/api/v1/clients/PP001/AB1234"
     * @param body          Raw request body ("" for GET requests)
     * @param receivedSig   The X-Signature header value
     */
    public static boolean verifySignature(
            String sharedSecret,
            String method,
            String path,
            String body,
            String receivedSig
    ) throws Exception {

        String message = method + "\n" + path + "\n" + (body != null ? body : "");

        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec keySpec = new SecretKeySpec(
            sharedSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"
        );
        mac.init(keySpec);

        byte[] hash = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        String expected = bytesToHex(hash);

        // Constant-time comparison
        return MessageDigest.isEqual(
            expected.getBytes(StandardCharsets.UTF_8),
            receivedSig.getBytes(StandardCharsets.UTF_8)
        );
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}


// ─── Example: Spring Boot filter ────────────────────────────
// @Component
// public class ArthamAuthFilter extends OncePerRequestFilter {
//     @Value("${artham.api-key}") private String arthamApiKey;
//     @Value("${artham.shared-secret}") private String arthamSecret;
//
//     @Override
//     protected void doFilterInternal(HttpServletRequest req,
//             HttpServletResponse res, FilterChain chain) throws ... {
//         String apiKey = req.getHeader("X-Api-Key");
//         String signature = req.getHeader("X-Signature");
//
//         if (!arthamApiKey.equals(apiKey)) {
//             res.sendError(401, "Unknown API key"); return;
//         }
//
//         String body = new String(req.getInputStream().readAllBytes());
//         if (!ArthamSignatureVerifier.verifySignature(
//                 arthamSecret, req.getMethod(),
//                 req.getRequestURI(), body, signature)) {
//             res.sendError(401, "Invalid signature"); return;
//         }
//         chain.doFilter(req, res);
//     }
// }

C# (.NET) — Verifying (API 1 & 2)

using System.Security.Cryptography;
using System.Text;

public static class ArthamSignatureVerifier
{
    /// <summary>
    /// Verify the HMAC-SHA256 signature sent by Artham.
    /// </summary>
    /// <param name="sharedSecret">The secret shared by Artham</param>
    /// <param name="method">HTTP method, e.g. "GET"</param>
    /// <param name="path">Request path, e.g. "/api/v1/clients/PP001/AB1234"</param>
    /// <param name="body">Raw request body ("" for GET)</param>
    /// <param name="receivedSignature">X-Signature header value</param>
    public static bool VerifySignature(
        string sharedSecret,
        string method,
        string path,
        string body,
        string receivedSignature)
    {
        string message = $"{method}\n{path}\n{body ?? ""}";

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(sharedSecret));
        byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
        string expected = BitConverter.ToString(hash).Replace("-", "").ToLower();

        // Constant-time comparison
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(receivedSignature)
        );
    }
}


// ─── Example: ASP.NET Core middleware ───────────────────────
// public class ArthamAuthMiddleware {
//     private readonly RequestDelegate _next;
//     private readonly string _apiKey;     // from appsettings.json
//     private readonly string _secret;     // from appsettings.json
//
//     public async Task InvokeAsync(HttpContext context) {
//         var apiKey = context.Request.Headers["X-Api-Key"].FirstOrDefault();
//         var signature = context.Request.Headers["X-Signature"].FirstOrDefault();
//
//         if (apiKey != _apiKey) {
//             context.Response.StatusCode = 401; return;
//         }
//
//         context.Request.EnableBuffering();
//         using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
//         var body = await reader.ReadToEndAsync();
//         context.Request.Body.Position = 0;
//
//         if (!ArthamSignatureVerifier.VerifySignature(
//                 _secret, context.Request.Method,
//                 context.Request.Path, body, signature)) {
//             context.Response.StatusCode = 401; return;
//         }
//         await _next(context);
//     }
// }

Python — Calling API 3

import hmac
import hashlib
import requests

ARTHAM_BASE   = "https://distributor-api.artham.co"   # Sandbox
API_KEY       = "artham_live_k8Fj2mNp..."
SHARED_SECRET = "your_shared_secret_here"
PATH          = "/api/v1/broker/holdings"


def sign(shared_secret, method, path, body=""):
    """HMAC-SHA256 of "{METHOD}\n{path}\n{body}" as lowercase hex."""
    message = f"{method}\n{path}\n{body}"
    return hmac.new(
        shared_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()


def fetch_holdings():
    response = requests.get(
        ARTHAM_BASE + PATH,
        headers={
            "X-Api-Key": API_KEY,
            # GET has no body, so the signed message is "GET\n{PATH}\n"
            "X-Signature": sign(SHARED_SECRET, "GET", PATH),
        },
        timeout=60,
    )
    response.raise_for_status()

    payload = response.json()
    if not payload["success"]:
        raise RuntimeError(payload["error"]["message"])

    data = payload["data"]

    # holdingCount is there so you can prove nothing was lost in transit
    if len(data["holdings"]) != data["holdingCount"]:
        raise RuntimeError("truncated response — do not store this snapshot")

    return data["asOf"], data["holdings"]


# ─── Daily job, after 07:00 IST ──────────────────────────────
as_of, rows = fetch_holdings()

# REPLACE the stored set — a closed position is expressed by its absence,
# so merging would keep exited positions alive forever.
replace_stored_holdings(as_of, rows)

Java — Calling API 3

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class ArthamHoldingsClient {

    private static final String BASE   = "https://distributor-api.artham.co"; // Sandbox
    private static final String PATH   = "/api/v1/broker/holdings";
    private static final String KEY    = "artham_live_k8Fj2mNp...";
    private static final String SECRET = "your_shared_secret_here";

    /**
     * HMAC-SHA256 of "{METHOD}\n{path}\n{body}" as lowercase hex.
     * Identical to the verification helper — only the use differs.
     */
    static String sign(String secret, String method, String path, String body)
            throws Exception {
        String message = method + "\n" + path + "\n" + body;

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] raw = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));

        StringBuilder hex = new StringBuilder(raw.length * 2);
        for (byte b : raw) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }

    /** Returns the raw JSON body — parse it with your JSON library. */
    public static String fetchHoldings() throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE + PATH))
                .header("X-Api-Key", KEY)
                // GET has no body, so the body component is the empty string
                .header("X-Signature", sign(SECRET, "GET", PATH, ""))
                .GET()
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            // 401 will not fix itself on a retry — check the key and the
            // signed path. Retry with backoff only on 5xx.
            throw new IllegalStateException(
                    "Artham returned " + response.statusCode() + ": " + response.body());
        }
        return response.body();
    }
}

C# (.NET) — Calling API 3

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

public class ArthamHoldingsClient
{
    private const string BaseUrl = "https://distributor-api.artham.co"; // Sandbox
    private const string Path    = "/api/v1/broker/holdings";
    private const string Key     = "artham_live_k8Fj2mNp...";
    private const string Secret  = "your_shared_secret_here";

    private static readonly HttpClient Http = new HttpClient();

    /// <summary>
    /// HMAC-SHA256 of "{METHOD}\n{path}\n{body}" as lowercase hex.
    /// </summary>
    public static string Sign(string secret, string method, string path, string body = "")
    {
        var message = $"{method}\n{path}\n{body}";

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));

        return Convert.ToHexString(hash).ToLowerInvariant();
    }

    /// <summary>Returns the raw JSON body — parse it with System.Text.Json.</summary>
    public static async Task<string> FetchHoldingsAsync()
    {
        var request = new HttpRequestMessage(HttpMethod.Get, BaseUrl + Path);
        request.Headers.Add("X-Api-Key", Key);
        // GET has no body, so the body component is the empty string
        request.Headers.Add("X-Signature", Sign(Secret, "GET", Path));

        var response = await Http.SendAsync(request);
        var payload  = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
        {
            // 401 means the key or the signed path is wrong, not a transient
            // fault — retry with backoff only on 5xx.
            throw new InvalidOperationException(
                $"Artham returned {(int)response.StatusCode}: {payload}");
        }
        return payload;
    }
}

8. Sandbox & Testing

Integration Steps

1. You share your sandbox base URL — e.g. https://sandbox-api.yourbroker.com, plus the receiver URL where Artham should push executed trades (API 2).
2. Artham shares credentials — We generate and send you an API Key + Shared Secret over email.
3. You build the API(s) — The Get Client Details endpoint (API 1) and the Executed Trades receiver (API 2).
4. You build the daily holdings pull — a scheduled job that calls GET /api/v1/broker/holdings after 07:00 IST and replaces your stored set (API 3). We will tell you when the endpoint is live on Sandbox.
5. End-to-end test — We call API 1 with test client codes, and POST test trade batches (NSE and BSE) to your API 2 receiver, verifying signature checks and idempotent dedupe. You call API 3 against Sandbox and we compare the snapshot against our books together.
6. Go live — You share the production base URL and receiver URL. We generate a new set of production credentials.

Test Checklist

Authentication — every API

API 1 & API 2 — the endpoints you host

API 3 — the holdings pull you make

Support

For integration questions, contact the Artham engineering team:

• Email: rahul@artham.co
• We are available for joint debugging calls during integration.