# Openclaw Skill

> SubventionAI — OpenClaw Skill

- Skill: `thewatcher01/openclaw-skill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add thewatcher01/openclaw-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thewatcher01/openclaw-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TheWatcher01 (https://skillmd.com/u/thewatcher01)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/thewatcher01/openclaw-skill

---

# SubventionAI — OpenClaw Skill

## Overview

**SubventionAI** is the intelligent French funding calendar for associations, IT companies, DevSecOps consultancies, AI startups, and RGPD compliance firms. This skill lets OpenClaw agents autonomously search subsidies, simulate eligibility, and track urgent funding deadlines.

---

## Authentication

All requests use an API key in the `Authorization` header:

```
Authorization: Bearer sk-<your-api-key>
```

**Obtain an API key:**

1. Log in to SubventionAI admin panel
2. Navigate to **Settings → API Keys**
3. Create a new key (role: `EDITOR`)
4. Copy the `sk-` prefixed key — shown **once only**

**Environment variables required:**

```bash
SUBVENTION_AI_URL=https://subvention-ia.fr   # Your SubventionAI instance
SUBVENTION_AI_KEY=sk-<your-key>                       # Your API key
```

---

## Base URL

```
${SUBVENTION_AI_URL}
```

---

## Endpoints

### 1. Agent Context Bootstrap

**GET** `/api/v1/agent/context`

No authentication required. Returns urgent deadlines, top open subsidies, aggregated stats, and available filter values in a single call. Use this as your **first message** to initialise context.

```bash
curl "${SUBVENTION_AI_URL}/api/v1/agent/context"
```

**Response structure:**

```json
{
  "timestamp": "2026-03-15T10:00:00Z",
  "urgentDeadlines": [
    {
      "id": "...",
      "name": "BPI France i-Nov",
      "deadline": "2026-04-30T00:00:00Z",
      "daysLeft": 46,
      "amountDisplay": "200 000 – 1 000 000 €",
      "sectors": ["ia", "numerique"]
    }
  ],
  "topOpenSubsidies": [...],
  "stats": { "total": 42, "openCount": 28, "waitingCount": 5 },
  "availableFilters": {
    "sectors": ["ia", "numerique", "cybersecurite", "devsecops", "rgpd", "social"],
    "fundingSources": ["BPI France", "ADEME", "France 2030"],
    "statuses": ["OPEN", "WAITING", "PERMANENT"]
  }
}
```

---

### 2. Search Subsidies

**GET** `/api/v1/subsidies`

```bash
# Search for DevSecOps + IA funding
curl "${SUBVENTION_AI_URL}/api/v1/subsidies?sectors=devsecops,ia&status=OPEN&limit=20" \
  -H "Authorization: Bearer ${SUBVENTION_AI_KEY}"

# Deadlines within 60 days
curl "${SUBVENTION_AI_URL}/api/v1/subsidies?deadlineBefore=$(date -d '+60 days' +%Y-%m-%d)&status=OPEN"

# Full-text search
curl "${SUBVENTION_AI_URL}/api/v1/subsidies?q=cybersecurite+numerique&limit=10"

# Cursor-based pagination (for iterating all results)
curl "${SUBVENTION_AI_URL}/api/v1/subsidies?limit=50&cursor=<nextCursor>"
```

**Query parameters:**

| Parameter        | Type    | Description                                                  |
| ---------------- | ------- | ------------------------------------------------------------ |
| `sectors`        | string  | Comma-separated: `numerique,ia,cybersecurite,devsecops,rgpd` |
| `sector`         | string  | Single sector (legacy compat)                                |
| `status`         | string  | `OPEN` \| `WAITING` \| `PERMANENT` \| `CLOSED`               |
| `region`         | string  | French region name                                           |
| `fundingSource`  | string  | Partial match on funding source                              |
| `priority`       | integer | 0 (highest) to 3 (lowest)                                    |
| `deadlineAfter`  | date    | ISO date: `2026-01-01`                                       |
| `deadlineBefore` | date    | ISO date: `2026-06-30`                                       |
| `amountMin`      | number  | Minimum amount in EUR                                        |
| `amountMax`      | number  | Maximum amount in EUR                                        |
| `q`              | string  | Full-text search (name + description)                        |
| `limit`          | integer | 1–100, default 50                                            |
| `offset`         | integer | Offset for pagination                                        |
| `cursor`         | string  | ID of last seen item (cursor pagination)                     |

---

### 3. Simulate Eligibility

**POST** `/api/v1/simulate`

No authentication required for public simulation.

#### Mode A — Association Loi 1901

```json
{
  "industry": "ASSOCIATION_FR",
  "sector": "social",
  "budgetRange": "50-100K",
  "region": "Ile-de-France",
  "memberCount": "10-50"
}
```

| Field         | Values                                     |
| ------------- | ------------------------------------------ |
| `budgetRange` | `<10K` \| `10-50K` \| `50-100K` \| `>100K` |
| `memberCount` | `<10` \| `10-50` \| `50-200` \| `>200`     |

#### Mode B — IT / DevSecOps / IA / RGPD

```json
{
  "industry": "IT",
  "sector": "devsecops",
  "region": "Ile-de-France",
  "annualRevenue": 800000,
  "employeeCount": 15,
  "ageYears": 4
}
```

| Field           | Values                                                          |
| --------------- | --------------------------------------------------------------- |
| `sector`        | `numerique` \| `ia` \| `cybersecurite` \| `devsecops` \| `rgpd` |
| `annualRevenue` | Annual revenue in EUR                                           |
| `employeeCount` | Number of employees                                             |
| `ageYears`      | Company age in years (default: 3)                               |

**IT Response structure:**

```json
{
  "data": {
    "industry": "IT",
    "sector": "devsecops",
    "matchCount": 4,
    "matches": [
      {
        "subsidyName": "BPI France — i-Nov / i-Demo Innovation",
        "subsidyCode": "BPI-INOV-2026",
        "eligibilityScore": 82,
        "estimatedAmountMin": 200000,
        "estimatedAmountMax": 1000000,
        "estimatedAmountDisplay": "200 000 – 1 000 000 €",
        "sourceUrl": "https://www.bpifrance.fr/..."
      }
    ]
  }
}
```

---

### 4. Health Check

**GET** `/api/health`

```bash
curl "${SUBVENTION_AI_URL}/api/health"
# {"status":"ok","timestamp":"2026-03-15T10:00:00Z"}
```

### 5. OpenAPI Spec

**GET** `/api/openapi.json`

Machine-readable OpenAPI 3.1 specification. Import into Postman, Swagger UI, or any OpenAPI client.

```bash
curl "${SUBVENTION_AI_URL}/api/openapi.json" | jq '.paths | keys'
```

---

## Admin API — Full Access with sk- Keys

All `/api/admin/*` routes accept API key authentication (`sk-` prefix). This gives OpenClaw agents complete programmatic access to the admin features:

| Endpoint                      | Method        | Description                                       |
| ----------------------------- | ------------- | ------------------------------------------------- |
| `/api/admin/stats`            | GET           | Dashboard statistics (counts, upcoming deadlines) |
| `/api/admin/subventions`      | GET, POST     | List + create subsidies                           |
| `/api/admin/subventions/[id]` | PATCH, DELETE | Update + delete subsidies                         |
| `/api/admin/checklists`       | GET, POST     | Manage application checklists                     |
| `/api/admin/checklists/[id]`  | PATCH, DELETE | Update + delete checklists                        |
| `/api/admin/alerts`           | GET           | Smart deadline alerts                             |
| `/api/admin/simulator`        | POST          | Advanced eligibility simulation (with DB data)    |
| `/api/admin/exports`          | GET           | Export data `?format=csv\|xlsx\|ical`             |
| `/api/admin/pipeline`         | GET, POST     | List runs + trigger lead-gen pipeline             |
| `/api/admin/prospects`        | GET           | Lead prospects + status updates                   |
| `/api/admin/organization`     | GET, PATCH    | Read/update org settings                          |
| `/api/admin/profile`          | GET, PATCH    | Read/update association profile                   |
| `/api/admin/ai-autofill`      | POST          | OCR/VLM extraction from CERFA images              |
| `/api/admin/push/send`        | POST          | Push notification to org subscribers              |

**Role mapping for API keys:**

| API key role  | Access                                       |
| ------------- | -------------------------------------------- |
| `VIEWER`      | GET endpoints only                           |
| `EDITOR`      | GET + POST + PATCH                           |
| `SUPER_ADMIN` | Full access + DELETE + pipeline + admin keys |

---

## Webhook Subscriptions — Push Events to OpenClaw

Register your OpenClaw gateway endpoint to receive real-time event pushes. **SOTA pattern for 2026 agent integration.**

### Supported events

| Event                | Triggered by                | Payload                                   |
| -------------------- | --------------------------- | ----------------------------------------- |
| `subsidy.deadline`   | Deadline cron (daily)       | List of subsidies with deadline ≤ 30 days |
| `subsidy.created`    | sync-aides-territoires cron | Count of new subsidies synced             |
| `subsidy.updated`    | Manual PATCH on subsidy     | Updated subsidy data                      |
| `pipeline.completed` | Lead-gen pipeline POST      | Run stats (processed, qualified, etc.)    |

### Register a webhook

```bash
curl -X POST "${SUBVENTION_AI_URL}/api/v1/webhooks" \
  -H "Authorization: Bearer ${SUBVENTION_AI_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://my-openclaw-gateway:42617/hooks/subvention",
    "events": ["subsidy.deadline", "pipeline.completed"]
  }'
```

**Response (signingSecret shown ONCE — store it securely):**

```json
{
  "success": true,
  "data": {
    "id": "clx...",
    "endpoint": "https://my-openclaw-gateway:42617/hooks/subvention",
    "events": ["subsidy.deadline", "pipeline.completed"],
    "signingSecret": "a3f9bc8d2e1...",
    "isActive": true,
    "createdAt": "2026-03-15T10:00:00Z"
  },
  "warning": "Conservez le signingSecret en lieu sûr — il ne sera plus retourné."
}
```

### Verify webhook signatures (OpenClaw side)

Every delivery includes `X-Webhook-Signature: t=<unix_ms>,v1=<hex>` in headers.

```rust
// OpenClaw webhook handler (pseudo-code)
fn verify_signature(secret: &str, body: &str, header: &str) -> bool {
    let parts: Vec<&str> = header.split(',').collect();  // ["t=1700000000", "v1=abc123"]
    let timestamp = parts[0].trim_start_matches("t=");
    let received_sig = parts[1].trim_start_matches("v1=");
    let payload = format!("{}.{}", timestamp, body);
    let expected = hmac_sha256(secret, &payload).to_hex();
    constant_time_eq(expected, received_sig)
}
```

### List webhooks

```bash
curl "${SUBVENTION_AI_URL}/api/v1/webhooks" \
  -H "Authorization: Bearer ${SUBVENTION_AI_KEY}"
```

### Unregister a webhook

```bash
curl -X DELETE "${SUBVENTION_AI_URL}/api/v1/webhooks/clx..." \
  -H "Authorization: Bearer ${SUBVENTION_AI_KEY}"
```

---

## Workflows

### Workflow 1 — DevSecOps Company Funding Discovery

```
1. GET /api/v1/agent/context
   → Extract availableFilters.sectors to confirm "devsecops" is available
   → Note urgentDeadlines with daysLeft < 30

2. POST /api/v1/simulate
   Body: { industry: "IT", sector: "devsecops", region: "Ile-de-France",
           annualRevenue: 800000, employeeCount: 15, ageYears: 4 }
   → Retrieve eligible funding programs with amounts + scores

3. GET /api/v1/subsidies?sectors=devsecops,ia&status=OPEN&limit=20
   → Get full subsidy details + application links

4. Compile report: eligible programs, estimated amounts, deadlines, next steps
```

### Workflow 2 — Deadline Monitoring (Weekly Agent Task)

```
1. GET /api/v1/subsidies?deadlineBefore=<30_days_from_now>&status=OPEN&sectors=ia,devsecops
   → List imminent deadlines

2. For each subsidy with deadline < 14 days:
   → Flag as URGENT
   → Generate summary with name, amount, deadline, link

3. Return structured alert for human review
```

### Workflow 3 — Full Funding Audit for New IT Client

```
1. GET /api/v1/agent/context → snapshot of current funding landscape
2. POST /api/v1/simulate (IT mode) → eligibility match for client profile
3. GET /api/v1/subsidies?sectors=<client.sectors>&status=OPEN → full catalogue
4. Cross-reference simulation matches with open subsidies
5. Generate prioritised action plan: which programs to apply for first
```

### Workflow 4 — Autonomous Lead Generation Pipeline

```
1. POST /api/admin/pipeline
   Body: { industry: "IT", maxEntities: 1000, dryRun: false }
   → Discover associations → enrich → evaluate eligibility → outreach
   Requires: SUPER_ADMIN role API key

2. GET /api/admin/pipeline/<runId> → track progress
3. GET /api/admin/prospects?status=QUALIFIED → review qualified leads
4. PATCH /api/admin/prospects/<id> → update lead status
```

### Workflow 5 — Checklist-Driven Application Tracking

```
1. GET /api/admin/stats → overview of open subsidies + upcoming deadlines
2. GET /api/admin/checklists → existing application dossiers
3. POST /api/admin/checklists
   Body: { subsidyId: "...", title: "Dossier BPI i-Nov 2026" }
4. PATCH /api/admin/checklists/<id>
   Body: { status: "IN_PROGRESS", notes: "Documents collectés le 2026-03-15" }
5. PATCH /api/admin/checklists/<id>
   Body: { itemId: "...", completed: true }  ← tick individual checklist items
```

### Workflow 6 — Event-Driven Architecture (with Webhooks)

```
1. Register webhook: POST /api/v1/webhooks
   → OpenClaw receives "subsidy.deadline" + "pipeline.completed" events

2. When event arrives at OpenClaw endpoint:
   a) Verify HMAC-SHA256 signature
   b) Parse payload by event type
   c) subsidy.deadline → trigger internal alert + suggest actions
   d) pipeline.completed → process new qualified leads automatically

3. No more polling — pure event-driven agent workflow
```

---

## Error Handling

| HTTP Status | Meaning           | Action                                        |
| ----------- | ----------------- | --------------------------------------------- |
| 200         | Success           | —                                             |
| 400         | Invalid JSON body | Fix request body                              |
| 401         | Unauthorized      | Check API key / JWT                           |
| 404         | Not found         | Check endpoint URL                            |
| 422         | Validation error  | Check `details` field for which params failed |
| 429         | Rate limited      | Slow down (1000 req/min per API key)          |
| 500         | Server error      | Retry after 5s, then escalate                 |

---

## Rate Limits

- **Public endpoints** (no auth): 20 req/min per IP
- **API key authenticated**: 1000 req/min per key

---

## OpenClaw Agent Example

```toml
# ~/.openclaw/skills/subvention-ai.toml
[skill]
name = "subvention-ai"
path = "~/.openclaw/skills/subvention-ai/"

[env]
SUBVENTION_AI_URL = "https://subvention-ia.fr"
SUBVENTION_AI_KEY = "sk-<your-key>"

[allowed_domains]
"subvention-ia.fr" = true
```

---

## Sector Reference

| Code            | Description                   |
| --------------- | ----------------------------- |
| `ia`            | Intelligence Artificielle     |
| `numerique`     | Numérique / ESN               |
| `cybersecurite` | Cybersécurité                 |
| `devsecops`     | DevSecOps / DevOps sécurisé   |
| `rgpd`          | Conformité RGPD / DPO         |
| `social`        | Action sociale (associations) |
| `sport`         | Sport (associations)          |
| `culture`       | Culture (associations)        |
| `education`     | Éducation / Formation         |
| `sante`         | Santé / Médico-social         |