Skip to main content

​
Overview

The corsa-integration skill teaches your AI coding assistant how to integrate with the Corsa compliance platform. It covers the full integration lifecycle from SDK installation to webhook handling.

​
What It Helps With

  • Setting up and configuring the @corsa-labs/sdk
  • Authentication with the correct Bearer <TOKEN>:<SECRET> format
  • Ingesting clients, members, accounts, wallets, sessions, and operations in the right order
  • Configuring webhook receivers with proper signature verification
  • Handling API errors, rate limits, and edge cases

​
Quick Start

After installing the skill, ask your AI assistant questions like:
  • “Set up the Corsa SDK in my project”
  • “Ingest an individual client with upsert”
  • “Create a deposit operation linked to a client”
  • “Set up a webhook handler for alert events”
  • “Handle Corsa API rate limiting”
Your assistant will generate code using the correct SDK patterns, authentication format, and entity relationships.

​
What the Skill Knows

​
SDK Setup & Authentication

  • CorsaClient initialization (not the deprecated ComplianceClient)
  • Bearer token format: Bearer <API_TOKEN>:<API_SECRET>
  • Base URLs for US (api.corsa.finance) and EU (api.eu.corsa.finance)
  • Rate limiting (500 req/60s) and Retry-After handling

​
Data Model & Ingestion Order

The skill understands the Corsa entity graph and enforces the correct ingestion order:
  1. Clients (Individual / Corporate)
  2. Members (UBOs, Directors — corporate only)
  3. Accounts & Wallets (Bank accounts, Blockchain wallets)
  4. Sessions (Device/IP data)
  5. Operations (Deposits, Withdrawals, Trades → Transactions)
  6. Alerts & Cases (linked to Clients and Transactions)

​
referenceId and Upsert

The skill knows that referenceId is your internal system ID for an entity, and that you can use either referenceId or the Corsa-generated id interchangeably in subsequent API calls. It guides correct upsert=true usage.

​
All 17 SDK Services

Full awareness of every service on CorsaClient: clients, members, deposits, withdrawals, trades, transactions, alerts, cases, bankAccounts, blockchainWallets, sessions, rules, ruleTemplates, evaluation, checklists, attachments, and platform.

​
Webhooks

Express handler setup with express.raw(), signature verification via verifyWebhookSignature, and all 24 event types.

​
Error Handling

ApiError structured errors with status, body, and requestId for debugging.

​
Common Mistakes It Prevents

MistakeWhat the skill does
Using Bearer <TOKEN> without the secretGenerates the correct Bearer <TOKEN>:<SECRET> format
Parsing webhook body as JSON before verificationUses express.raw() and verifies the raw buffer
Creating operations before clientsFollows the data model dependency order
Using deprecated ComplianceClientAlways uses CorsaClient
Omitting referenceIdIncludes it and explains upsert behavior
Ignoring rate limitsAdds Retry-After handling to error logic

​
Source

GitHub Repository

View the full skill source, including the detailed API reference with all method signatures and code templates.