gru_emoney_token-factory/docs/api/integration-cookbook.md

# Integration Cookbook

This document provides step-by-step guides for common integration flows.

## Table of Contents

1. [Deploy a Token](#deploy-a-token)
2. [Place a Lien](#place-a-lien)
3. [Submit ISO-20022 Message](#submit-iso-20022-message)
4. [Generate and Dispatch Packet](#generate-and-dispatch-packet)
5. [Bridge Lock/Unlock](#bridge-lockunlock)

## Deploy a Token

### REST API

```bash
POST /v1/tokens
Authorization: Bearer <token>
Idempotency-Key: <uuid>

{
  "name": "USD Wrapped",
  "symbol": "USDW",
  "decimals": 18,
  "issuer": "0x1234...",
  "defaultLienMode": "ENCUMBERED",
  "bridgeOnly": false
}
```

### GraphQL

```graphql
mutation {
  deployToken(input: {
    name: "USD Wrapped"
    symbol: "USDW"
    decimals: 18
    issuer: "0x1234..."
    defaultLienMode: ENCUMBERED
  }) {
    code
    address
    policy {
      lienMode
    }
  }
}
```

## Place a Lien

### REST API

```bash
POST /v1/liens
Authorization: Bearer <token>

{
  "debtor": "0xabcd...",
  "amount": "1000000000000000000",
  "priority": 1,
  "reasonCode": "DEBT_ENFORCEMENT"
}
```

### GraphQL

```graphql
mutation {
  placeLien(input: {
    debtor: "0xabcd..."
    amount: "1000000000000000000"
    priority: 1
    reasonCode: DEBT_ENFORCEMENT
  }) {
    lienId
    amount
    active
  }
}
```

## Submit ISO-20022 Message

### Inbound (from rail adapter)

```bash
POST /v1/iso/inbound
Authorization: Bearer <token> (or mTLS)
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "msgType": "pacs.008",
  "instructionId": "0x1234...",
  "payloadHash": "0xabcd...",
  "payload": "<Document>...</Document>",
  "rail": "FEDWIRE"
}
```

### Outbound (from client)

```bash
POST /v1/iso/outbound
Authorization: Bearer <token>
Idempotency-Key: <uuid>

{
  "msgType": "pain.001",
  "instructionId": "0x1234...",
  "payloadHash": "0xabcd...",
  "payload": "<Document>...</Document>",
  "rail": "SEPA",
  "token": "0x5678...",
  "amount": "1000000000000000000",
  "accountRefId": "0xdef0...",
  "counterpartyRefId": "0x9876..."
}
```

## Generate and Dispatch Packet

### Step 1: Generate Packet

```bash
POST /v1/packets
Authorization: Bearer <token>
Idempotency-Key: <uuid>

{
  "triggerId": "abc123...",
  "channel": "PDF"
}
```

### Step 2: Dispatch Packet

```bash
POST /v1/packets/{packetId}/dispatch
Authorization: Bearer <token>
Idempotency-Key: <uuid>

{
  "channel": "EMAIL",
  "recipient": "recipient@example.com"
}
```

### Step 3: Record Acknowledgement

```bash
POST /v1/packets/{packetId}/ack
Authorization: Bearer <token>
Idempotency-Key: <uuid>

{
  "status": "ACCEPTED",
  "ackId": "ack-123"
}
```

## Bridge Lock/Unlock

### Lock Tokens

```bash
POST /v1/bridge/lock
Authorization: Bearer <token>

{
  "token": "0x1234...",
  "amount": "1000000000000000000",
  "targetChain": "0x0000...0001",
  "targetRecipient": "0xabcd..."
}
```

### Unlock Tokens

```bash
POST /v1/bridge/unlock
Authorization: Bearer <token>
Idempotency-Key: <uuid>

{
  "lockId": "lock-123",
  "token": "0x1234...",
  "to": "0xabcd...",
  "amount": "1000000000000000000",
  "sourceChain": "0x0000...0001",
  "sourceTx": "0x5678...",
  "proof": "0xdef0..."
}
```

## Webhook Integration

### Register Webhook

```bash
POST /v1/webhooks
Authorization: Bearer <token>

{
  "url": "https://example.com/webhooks",
  "events": ["triggers.created", "liens.placed"],
  "secret": "webhook-secret"
}
```

### Webhook Payload

```json
{
  "eventId": "uuid",
  "eventType": "triggers.created",
  "occurredAt": "2024-01-01T00:00:00Z",
  "payload": {
    "triggerId": "abc123...",
    "rail": "FEDWIRE"
  },
  "signatures": [{
    "signer": "system",
    "signature": "hmac-sha256-signature"
  }]
}
```

### Verify Webhook Signature

```javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const expectedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```