ARTHAM

Broker Integration API Specification

Version 1.1  ·  July 2026

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) API to fetch client information.

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.

API Summary

Base URL

You provide Artham with your base URL. All endpoint paths below are appended to it.

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

2. Authentication

Every request from Artham includes two headers for authentication:

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 the API Key to identify incoming requests from Artham, and the Shared Secret to verify the signature.

Signature Computation

Artham computes the signature as follows:

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

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

Verification Steps (Your Side)

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.

See Section 6 for complete verification code in Python, Java, and C#.

3. Error Handling

Response Envelope

All responses must follow this structure:

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 — Consent Status Update Required

When an order is generated for a client, Artham sends the client a consent request on WhatsApp (Approve / Cancel buttons) and email (OTP). The moment the client responds, Artham calls this API on your server — so you know which client approved and which client cancelled, along with the transaction details (scrip, quantity, price, amount).

You provide Artham with the URL where you want to receive these notifications. Authentication uses the same X-Api-Key + X-Signature headers described in Section 2 (signature computed over the raw request body).

{
  "eventId": "consent-1042",
  "clientCode": "AB1234",
  "clientName": "Rajesh Kumar",
  "requestType": "REBALANCE",
  "referenceId": "REB#210",
  "status": "APPROVED",
  "respondedVia": "WHATSAPP",
  "respondedAt": "2026-07-15 14:32:08",
  "orders": [
    {
      "symbol": "TCS",
      "exchange": "NSE",
      "transactionType": "SELL",
      "quantity": 10,
      "price": 3450.50,
      "amount": 34505.00
    },
    {
      "symbol": "HDFCBANK",
      "exchange": "NSE",
      "transactionType": "BUY",
      "quantity": 20,
      "price": 1720.00,
      "amount": 34400.00
    }
  ]
}

{
  "success": true
}

6. Signature Verification — Code Samples

Below are complete examples showing how to verify the X-Signature header on your server. Use the approach that matches your tech stack.

Python

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/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

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/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)

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/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);
//     }
// }

7. Sandbox & Testing

Integration Steps

1. You share your sandbox base URL — e.g. https://sandbox-api.yourbroker.com, plus the API URL where you want consent status updates (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 Consent Status API receiver (API 2).
4. End-to-end test — We call your API with test client codes, trigger test consent requests on WhatsApp (one Approve, one Cancel), and verify both directions.
5. Go live — You share the production base URL and API URL. We generate a new set of production credentials.

Test Checklist

Support

For integration questions, contact the Artham engineering team:

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