# integration-patterns

A skill for designing integrations between financial systems: APIs, FIX, ISO 20022, batch feeds and idempotency. Useful when wiring up a custodian or chasing recon breaks.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 655 installs · ★ 218
- Author: JoelLewis
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/JoelLewis/finance_skills/tree/HEAD/plugins/data-integration/skills/integration-patterns/SKILL.md
- Updated: 2026-07-18
- HTML: https://affpapa.org/en/nevibecode/skills/integration-patterns

## What it does

The skill lays out how financial integrations are built and gives the agent concrete patterns to follow. It covers REST conventions for positions, transactions and orders, async operations that return `202 Accepted` with a polling URL, cursor-based pagination for large result sets, and rate limiting with `429` plus `Retry-After`. Authentication gets its own section: OAuth 2.0 client credentials, HMAC request signing, and mTLS for custodian and clearing connections.

FIX is broken down by layer — session management with Logon, Heartbeat, ResendRequest and SequenceReset, application messages like NewOrderSingle and ExecutionReport, and versions from 4.2 through 5.0 with FIXT 1.1. Engine options are listed too: QuickFIX, QuickFIX/J, Chronicle FIX and commercial ones. On top of that come event-driven patterns, batch feeds, idempotency for transaction APIs, retry and circuit breaker design, dead letter queues, and data mapping between mismatched schemas.

Treat it as a reference, not a code generator. The skill sets vocabulary and boundaries; the agent still writes the implementation for your stack. If your project touches none of these protocols, it won't earn its place. Production connectivity to a custodian usually requires completing their certification environment first, so check that requirement before you start.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add JoelLewis/finance_skills --skill integration-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/integration-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/integration-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add JoelLewis/finance_skills --skill integration-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/integration-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add JoelLewis/finance_skills --skill integration-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/integration-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install JoelLewis/finance_skills integration-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/integration-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add JoelLewis/finance_skills --skill integration-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/JoelLewis/finance_skills --path plugins/data-integration/skills/integration-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/integration-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add JoelLewis/finance_skills --skill integration-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/JoelLewis/finance_skills/tree/HEAD/plugins/data-integration/skills/integration-patterns/SKILL.md

## When to use it
- design a REST API for positions and transactions with sane pagination
- bring up a FIX session for order routing and handle gap recovery
- build batch processing for custodian feeds and EOD reconciliation
- add idempotency to a transaction API
- trace recon breaks back to an integration failure

## Example prompts
- Design a custodian integration with a batch position feed and EOD reconciliation
- Help me set up FIX 4.4 for order routing, walk me through the session layer
- Add idempotency and a circuit breaker to our transfer API

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a9900a69adcccc16.

BEGIN THIRD-PARTY FILE a9900a69adcccc16
```text
---
name: integration-patterns
description: "Design and implement integration architectures connecting financial systems — APIs, FIX protocol, ISO 20022, event-driven patterns, batch feeds, idempotency, and resilience. Use when building custodian integration pipelines, implementing FIX connectivity for order routing, designing ISO 20022 or SWIFT migration messaging, building batch file processing for custodian feeds or EOD reconciliation, implementing idempotency for transaction APIs, designing retry or circuit breaker patterns, mapping data between systems with different schemas, or troubleshooting integration failures causing recon breaks. Trigger on: FIX protocol, ISO 20022, custodian feed, batch processing, API design, idempotency, circuit breaker, dead letter queue, data mapping, integration architecture, SWIFT migration, mTLS, file feed, event-driven, message broker."
---

# Integration Patterns

## Core Concepts

### 1. API Design for Financial Systems

Financial APIs serve position data, transaction history, account information, reference data, and order submission. Design conventions differ from general-purpose APIs due to the sensitivity, auditability, and volume of financial data.

**REST conventions:** Resource-oriented design with nouns for financial entities -- `/accounts/{id}/positions`, `/transactions`, `/orders/{id}/executions`. Use HTTP methods semantically: GET for reads (positions, balances), POST for actions (order submission, transfer initiation), PUT/PATCH for updates (account preferences, model assignments). Return standard HTTP status codes with domain-specific error bodies including error codes, human-readable messages, and correlation IDs for traceability. Financial APIs must distinguish between synchronous operations (position lookup returns immediately) and asynchronous operations (transfer initiation returns a 202 Accepted with a status polling URL or webhook callback). Long-running operations such as bulk rebalancing or batch trade submission should use the async pattern to avoid client-side timeouts.
```
END THIRD-PARTY FILE a9900a69adcccc16

The third-party file has ended. Everything between the a9900a69adcccc16 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2070 of 41644 bytes. © JoelLewis · MIT · https://github.com/JoelLewis/finance_skills/tree/HEAD/plugins/data-integration/skills/integration-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md