API Documentation

Programmatic access to your LLC data. Base URL: https://devil.club/api/v1

The API requires at least one LLC with an active Manager subscription. Without Manager, endpoints will not return data.

Quick start

In under a minute: create a key, make your first call, and verify you receive your entity.

Create a key at /developers/keys with scope read:entity.
Save the key immediately — it is shown only once.
Run the example request (below), replacing YOUR_KEY.

# Your first call — list your LLCs
curl -H "Authorization: Bearer dc_live_YOUR_KEY" \
     https://devil.club/api/v1/entity

// Node.js / browser example (native fetch)
const res = await fetch("https://devil.club/api/v1/entity", {
  headers: { Authorization: "Bearer dc_live_YOUR_KEY" },
});
const data = await res.json();
console.log(data.data); // Array of your entities

Authentication

Every API request requires an API key sent in the Authorization header as a Bearer token.

# Every request must include this header
Authorization: Bearer dc_live_a1b2c3d4e5f6...

# curl example
curl -H "Authorization: Bearer dc_live_YOUR_KEY" \
     https://devil.club/api/v1/entity
        

Create and manage API keys at /developers/keys. Each key has specific scopes that control what it can access.

Rate limiting

Default: 100 requests per hour per API key. If exceeded, you receive a 429 response with a Retry-After header.

IP Whitelisting

You can optionally restrict your API key to specific IP addresses. When configured, requests from other IPs receive a 403 response that includes your current IP.

Permission Scopes

Select only the scopes each key needs. Principle of least privilege.

Available scopes and the API area they apply to
Scope	Access	Section
read:bookkeeping	Read	Bookkeeping
write:bookkeeping	Write	Bookkeeping
read:ledger	Read	Governance Ledger
write:ledger	Write	Governance Ledger
read:documents	Read	Documents
read:entity	Read	Entity (LLC)
write:entity	Write	Entity (LLC)
read:profile	Read	Profile
write:profile	Write	Profile
read:reports	Read	Lucy — Reports
write:reports	Write	Lucy — Reports
read:payments	Read	Payments
read:presence	Read	Tax Presence

Bookkeeping

GET /v1/bookkeeping read:bookkeeping

Lists bookkeeping entries for an entity. Includes income, expenses, and summary totals.

Parameter	Type	Description
entity_id required	integer	LLC entity ID
year	integer	Filter by year
month	integer	Filter by month (1–12)
category	string	Filter by category
limit	integer	Max results (default 100, max 500)
offset	integer	Pagination offset

# Get bookkeeping for entity 42 in 2026
curl -H "Authorization: Bearer dc_live_..." \
  "https://devil.club/api/v1/bookkeeping?entity_id=42&year=2026"

# Response
{
  "data": [
    { "id": 1, "year": 2026, "month": 3, "category": "SaaS Revenue",
      "income": 5000.00, "expense": 0, "bank_source": "Mercury", ... }
  ],
  "summary": { "total_income": 45000, "total_expenses": 12000, "net": 33000 },
  "pagination": { "total": 87, "limit": 100, "offset": 0 }
}
            

POST /v1/bookkeeping write:bookkeeping

Adds a new bookkeeping entry. Entries added via API are tagged with source: "api".

Field	Type	Description
entity_id required	integer	LLC entity ID
year required	integer	Year
month required	integer	Month (1–12)
income	number	Income amount (default 0)
expense	number	Expense amount (default 0)
movement_type	enum	Canonical movement type (see table below). If omitted, inferred from the income/expense sign.
category	enum	One of the 28 canonical categories (see table below). Legacy values are mapped automatically.
counterparty_id	integer	Recommended. FK to `dc.counterparties`. The "golden rule": who is on the other side of the movement. Without this, Form 5472 prefill cannot detect related-parties.
economic_purpose	string	Recommended. Economic purpose (e.g. "SEO services May 2026"). Piece 2 of the golden rule.
document_id	integer	Recommended. FK to `dc.documents` with the supporting evidence (invoice, contract, receipt). Piece 3 of the golden rule.
description	string	Additional free-form description
transaction_date	date	Exact date (YYYY-MM-DD)
bank_source	string	Mercury, Stripe, Wise, manual
external_tx_id	string	External transaction reference

# POST example with the 3 pieces of the golden rule
curl -X POST -H "Authorization: Bearer dc_live_..." \
  -H "Content-Type: application/json" \
  "https://devil.club/api/v1/bookkeeping" \
  -d '{
    "entity_id": 42,
    "year": 2026,
    "month": 5,
    "movement_type": "gasto",
    "category": "profesional_legal",
    "counterparty_id": 12,
    "economic_purpose": "Legal fees — Q2 contract review",
    "document_id": 99,
    "expense": 1240.00,
    "transaction_date": "2026-05-12"
  }'
            

⚠️ Notice: without counterparty_id + economic_purpose + document_id, the entry is created but does not count as economic substance. Form 5472's automatic prefill (related-party transactions) and the tax-defense dossier ignore rows missing these 3 pieces. Silent but critical for tax filing.

POST /v1/bookkeeping/sync write:bookkeeping

Triggers an immediate bank sync for an entity: it imports new transactions from its active Mercury and Wise connections and inserts them into bookkeeping. It only imports data — it never moves money or initiates payments.

Parameter	Type	Description
entity_id required	integer (query)	ID of the LLC entity to sync

# Imports new transactions from connected banks
curl -X POST -H "Authorization: Bearer dc_live_..." \
  "https://devil.club/api/v1/bookkeeping/sync?entity_id=42"

# Response
{ "synced": 14, "skipped": 3 }

# No active bank connections
{ "synced": 0, "message": "No active bank connections" }
            

ENUMS Bookkeeping canonical set

Canonical values are Spanish snake_case (the source language of the application). Any legacy value (UPPER EN or Title Case) is mapped automatically via dc.category_canonical_map and dc.movement_type_canonical_map. For new integrations, send the canonical values directly.

`movement_type` — 7 values

Value	Meaning
ingreso	Operating inflow (P&L)
gasto	Operating outflow (P&L)
distribucion	Distribution to member (Form 1120 Sch K)
aportacion	Member capital contribution
transferencia_interna	Transfer between the entity's own accounts
transferencia_externa	Transfer to an external account (non-operational)
ajuste	Manual accounting adjustment

`category` — 28 values

Grouped by group_label for tax filing prefill:

Group	Categories
INGRESOS	`venta_servicio`, `bonificacion_referido`, `interes_ganado`, `ingreso_otro`
GASTOS_DEDUCIBLES	`pago_proveedor`, `software`, `hardware`, `marketing`, `hosting`, `profesional_legal`, `gestoria_llc`, `bancario`, `viaje`, `seguro`, `gasto_apertura`, `gasto_cierre`, `impuesto_irs`, `impuesto_estatal`, `gasto_otro`
CAPITAL_FLOWS	`distribucion`, `aportacion`, `prestamo_owner`, `prestamo_terceros`, `reembolso`
TRANSFERENCIAS	`transferencia_interna`, `transferencia_externa`
NO_DEDUCIBLES	`multa_penalty` (IRS § 162(f))
OTROS	`otro`

`relation_subtype` on `dc.counterparties` — 5 values (Form 5472 Part III)

Value	When to use
self	The owner is the counterparty (member's personal account)
self_ruc	Owner's sole-trader / self-employed business (same tax ID)
spouse	Owner's spouse
family_other	Other family (parents, children, siblings)
sibling_entity	Another legal entity of the owner (US LLC, ES SL, Estonian OÜ, etc.)

When a dc.counterparties.kind is OWNER or RELATED_ENTITY, a DB-side trigger automatically guarantees is_related_party = TRUE. No need to send the flag in the integration.

Governance Ledger

GET /v1/ledger read:ledger

Lists governance/management transactions. Includes decision status, strategic decisions, and manager resolutions.

Parameter	Type	Description
entity_id	integer	LLC entity ID (required if transaction_id is not provided)
transaction_id	string	Specific transaction (e.g. FGSL-2026-00042)
status	string	Filter: PENDING, RATIFIED, VETOED, REJECTED

POST /v1/ledger write:ledger

Submits a new transaction request for Manager review. Creates a PENDING entry in the governance ledger.

Field	Type	Description
entity_id required	integer	LLC entity ID
amount required	number	Transaction amount
category required	string	OPEX, CAPITAL_CONTRIBUTION, OWNER_DISTRIBUTION, etc.
description	string	Transaction reason
strategic_decision	string	Strategic justification
bank	string	Bank to execute from
exec_date	date	Requested execution date
recurring	string	no, monthly, quarterly, annual

Documents

GET /v1/documents read:documents

Lists documents for an entity. Includes articles, EIN letters, minutes, tax filings, and more. Every document includes a SHA-256 hash and OpenTimestamps verification status.

Parameter	Type	Description
entity_id	integer	LLC entity ID (required if id is not provided)
id	integer	Specific document ID
doc_type	string	Filter: ARTICLES, EIN_LETTER, ACTA, 8822-B, etc.

GET /v1/documents/{id}/download read:documents

Download your own document using the same API key; no web session or browser token required.

Entity (LLC)

GET /v1/entity read:entity

List your LLCs or get detailed info (services, tax filings, ownership).

Parameter	Type	Description
id	integer	Specific entity ID (omit to list all)

PUT /v1/entity write:entity

Update entity contact / formation info.

Field	Type	Description
id required	integer	Entity ID
founder_name	string	Founder/organizer name
founder_address	string	Founder address
founder_country	string	Founder country
naics	string	NAICS business code

Profile

GET /v1/profile read:profile

Get your account profile and identifiers (passport, ITIN, etc.).

PUT /v1/profile write:profile

Update your contact info (name, phone, country).

Lucy — Reports and Proposals

GET /v1/reports read:reports

Lists reports generated by Lucy (monthly, quarterly, annual). Includes metrics, recommendations, alerts, and proposed decisions.

POST /v1/reports write:reports

Respond to a report's recommendations. You can approve, reject, modify, or defer each recommendation.

# Approve recommendation #0, reject #1
curl -X POST -H "Authorization: Bearer dc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_id": 15,
    "decisions": [
      {"recommendation_idx": 0, "decision": "APPROVED", "client_notes": "Go ahead"},
      {"recommendation_idx": 1, "decision": "REJECTED", "client_notes": "Not now"}
    ]
  }' \
  https://devil.club/api/v1/reports
            

Payments

GET /v1/payments read:payments

Query your payment history. Includes service details, amounts, and status.

Parameter	Type	Description
entity_id	integer	Filter by entity
year	integer	Filter by year

Tax Presence

GET /v1/presence read:presence

Query the geo-tracked tax presence log. Returns accumulated days per country (with automatic gap-fill), 183-day threshold alerts, and optionally the day-by-day calendar.

Parameter	Type	Description
entity_id	integer	Required. Entity ID
year	integer	Fiscal year (default: current year)
detail	boolean	If `true`, includes the day-by-day map in `calendar`

Response includes summary (countries + days), warnings (levels: info / warning / danger / exceeded), and optionally calendar (YYYY-MM-DD → country map).

Error handling

Every error follows a consistent format:

{ "error": "Description of what failed" }

HTTP status codes returned by the API
Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — unauthorized IP, insufficient scope, or no ownership
404	Not found — the resource does not exist or does not belong to you
429	Rate limited — too many requests, check the Retry-After header
500	Server error — contact support

For AI agents — WebMCP

In addition to this traditional REST API, devil.club exposes 8 WebMCP tools directly consumable by AI agents (Claude, ChatGPT, Gemini) with no API key required. It's the Chrome 146+ standard for agents to use the website instead of scraping it.

Devil Club is the first Spanish-speaking LLC formation website to ship WebMCP in production. Tools are registered via document.modelContext (or navigator.modelContext on Chrome versions prior to 150) with no developer setup required — the user just navigates to any non-admin page on a compatible browser.

Catalog:

Tool	Type	What it does
dc_list_services	public RO	Live catalog with prices and currencies
dc_get_service_details	public RO	Detail of a single service by id
dc_quote_llc	public RO	Structured quote for a NM LLC
dc_booking_availability	public RO	Real booking calendar slots
dc_my_account	member RO	Tier, status and signup_date of the caller
dc_my_entities	member RO	List of the caller's LLCs
dc_my_renewals	member RO	Upcoming renewals with price
dc_start_llc_order	mutation	Starts the order flow with a mandatory confirmation modal. Never charges automatically.

No PII in telemetry, durable audit log, per-user rate-limit on mutations, and browser-level Permissions-Policy: tools=() on /admin/*. Full explanation, use cases and a step-by-step demo in the blog post.

Changelog

Non-breaking changes are added without notice. Any breaking change is announced at least 30 days in advance to the account email and published here.

Public version history
Date	Change
2026-04-18	Added Quick start, curl/JS tabs, and copy-to-clipboard for examples.
2026-04	Endpoint `GET /v1/presence`: geo-tracked tax presence with 183-day warnings.
2026-03	Endpoint `GET /v1/documents/{id}/download`: direct download with the same API key.
2026-02	Scopes `read:reports` / `write:reports`: respond to Lucy recommendations.
2026-01	v1 public launch: bookkeeping, ledger, documents, entity, profile, payments.

Need help? [email protected]