> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reconifyhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract.
> The public OpenAPI document contains only the documented external /v2 contract.

# Integrate with an AI agent

> Hand Reconify to a coding agent and get a correct sender on the first try.

A coding agent such as Claude Code, Cursor, GitHub Copilot, or Codex can add Reconify
event tracking to your codebase, provided it works from the published API instead of
invented endpoints and field names. The prompt below keeps it there.

One thing stays with you: the credential. The `write` key comes from
**Dashboard → Settings → API Keys** and goes into your secret manager as
`RECONIFY_API_KEY`, because an agent has no business creating credentials or deciding
where secrets live.

<Warning>
  An API key never belongs in a prompt, a rules file, or a chat window. The prompt below has
  the agent read the key from the environment.
</Warning>

Which flow to use is not a decision you make up front. The prompt has the agent work
that out from your code and confirm it with you.

## Copy this prompt

The prompt runs in four phases and stops for your approval twice, because an agent that
starts writing a sender before it understands how your money moves maps the wrong
identifiers, and the mapping is the expensive part to fix later. It carries no
project-specific detail on purpose, since discovering that is the agent's first job.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
I want to add Reconify monitoring to this project. Reconify receives
money-movement events and raises findings when expected evidence is missing,
late, or mismatched.

Work in four phases. Stop and wait for my approval where I say so. Do not
change any file before phase 4.

PHASE 1 — Understand how money moves in this project.
Read the codebase and answer:
- Where does money actually move? Find the payment, wallet, ledger, payout, and
  order-fulfillment paths.
- What does each of those paths record when it completes or fails? Name the
  functions, domain events, webhook handlers, queue messages, or table writes.
- What identifier ties a payment to its downstream effect? For example, what
  value connects "customer paid" to "wallet was credited"?
- What identifies the account or object being credited or debited?
- How are monetary amounts stored: integer minor units, decimal, or float? What
  currencies exist?
- Where is the natural place to emit an outbound call after each of these
  completes?
Report what you found. Do not read the Reconify docs yet.

PHASE 2 — Learn the Reconify model.
Now read, in this order:
1. https://docs.reconifyhq.com/concepts/overview
2. https://docs.reconifyhq.com/concepts/operations
3. https://docs.reconifyhq.com/reference/api/welcome
Summarize back to me, in your own words: what a flow is, what an operation is,
the difference between `reference` and `entity_id`, and which of the four flows
exist along with the evidence and deadline each one expects.

PHASE 3 — Propose a mapping. STOP after this and wait for my approval.
Produce a table with one row per money-movement path you found in phase 1:
| My code path | Reconify flow | Reconify event type | My value for reference | My value for entity_id | My value for amount and currency | Where it will be emitted |
Then tell me:
- Which flows I can monitor today, and which ones my code cannot yet support
  because it does not record the required evidence.
- Any place where my identifiers do not cleanly map, and what you recommend.
- Whether amounts need converting to a decimal string.
- Which integration path you recommend: @reconifyhq/sdk for TypeScript,
  reconify-python for Python, or a direct REST call in another language.
Do not write code yet. Wait for me to confirm or correct the mapping.

PHASE 4 — Plan, then implement.
After I approve the mapping, write an implementation plan covering the sender,
where it is called, configuration, error handling, and tests. Wait for my
approval of the plan, then implement it.

Rules that apply throughout:
- Do not change my database schema or my existing domain events. Add a
  translation layer over what I already emit.
- Read the key from the RECONIFY_API_KEY environment variable. Never hardcode
  it, log it, or expose it to a client.
- `amount` is a decimal string such as "150.00", never a number or a float.
- Set a stable event `id` derived from my source system's identifier so retries
  are safe.
- Read every item in the `results` array of an ingestion response. `index` maps
  back to the event sent. Log rejected items with their code, field, and
  message. Treat `duplicate` as delivered. Alert on `idempotency_conflict`.
- Do not invent endpoints. The public API is only what is listed at
  https://docs.reconifyhq.com/reference/api/welcome. There are no webhooks.
- Tests must use a fake HTTP client. Never call the live API from a test.
```

<Tip>
  An agent with subagents or a plan mode does best when it uses them for phase 1. Finding
  every money-movement path in a large codebase is a search problem, and the quality of the
  mapping depends entirely on that search being complete.
</Tip>

## Check what it produced

The mapping the agent proposes is the deliverable worth scrutinizing. A correct one names
your own identifiers rather than repeating the documentation:

| My code path                       | Flow                | Event type          | `reference`        | `entity_id`         | Amount                         |
| ---------------------------------- | ------------------- | ------------------- | ------------------ | ------------------- | ------------------------------ |
| `PaymentService.capture()` success | `payment_to_wallet` | `payment.succeeded` | `payment.order_id` | `payment.wallet_id` | `Decimal(cents)/100` as string |
| `WalletService.credit()` commit    | `payment_to_wallet` | `wallet.credited`   | `credit.order_id`  | `credit.wallet_id`  | same                           |

Each value has to serve its own role: `reference` correlates an operation, and `entity_id`
identifies its wallet or order. The contract allows the same source identifier in both
roles where that is genuinely correct.

Six mistakes account for most of what agents get wrong against this API:

<AccordionGroup>
  <Accordion title="amount sent as a number">
    `"amount": 150.00` is rejected. It must be `"amount": "150.00"`. Watch for a
    `float` in Python or a bare number in JavaScript.
  </Accordion>

  <Accordion title="reference and entity_id swapped">
    `reference` correlates the operation, and `entity_id` names the wallet or order.
    Swapping them produces events that never correlate, so every operation looks
    incomplete.
  </Accordion>

  <Accordion title="Random event IDs">
    A `uuid4()` generated at send time defeats retry safety. The ID must be derived
    from the source system so the same event produces the same ID twice.
  </Accordion>

  <Accordion title="Results ignored">
    A `202` response does not mean every event was stored. If the code does not loop
    over `results`, rejections are silent.
  </Accordion>

  <Accordion title="An invented webhook handler">
    There is no outbound webhook. If the agent added a `/webhooks/reconify` route,
    delete it and poll `GET /v2/issues?status=open` instead.
  </Accordion>

  <Accordion title="Tests that call the live API">
    There is no sandbox. Tests must use a fake HTTP client. Both SDKs support this:
    pass `fetch` in TypeScript, or `http_client` in Python.
  </Accordion>
</AccordionGroup>

## Keep the rules in your repo

Agents forget prompts between sessions, and a rules file does not. The text below belongs
in `AGENTS.md` at your repository root, on its own or appended to an existing file. Claude
Code, Cursor, Codex, and several other tools read it automatically.

<Accordion title="AGENTS.md rules for Reconify">
  ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
  ## Reconify monitoring

  Reconify receives money-movement events from this codebase and raises findings
  when expected evidence is missing, late, or mismatched.

  Reference: https://docs.reconifyhq.com

  ### Contract rules

  - The only public API is `/v2` at `https://api.reconifyhq.com`. Never call
    `/business/v1`, which is internal and not part of the public contract.
  - There are no outbound webhooks. To learn about new findings, poll
    `GET /v2/issues?status=open`.
  - There is no sandbox or test mode. Every request reaches the real
    organization. Never call the live API from an automated test.
  - Authentication is `Authorization: Bearer rk_...` read from
    `RECONIFY_API_KEY`. `read` keys authorize GET, `write` keys authorize POST
    and PATCH.

  ### Event fields

  Required on every event: `flow`, `type`, `reference`, `entity_id`.
  Also required unless the type is `payment.failed` or `payout.failed`:
  `amount`, `currency`.

  - `amount` is a decimal **string** such as `"150.00"`. Never a number.
  - `currency` is a three-letter uppercase ISO code.
  - `occurred_at` is RFC 3339 UTC.
  - `reference` identifies the operation. `entity_id` identifies the wallet or
    order. Map each field by its role, and never swap them.
  - `id` is optional but should always be set, as `evt_` plus 26 uppercase
    alphanumeric characters, so retries are safe.
  - Unknown fields are rejected. Put extra context in `metadata` (flat, at most
    20 keys) or in `data` for provider details.

  Valid `flow` values: `payment_to_wallet`, `payment_to_order`,
  `wallet_to_wallet`, `wallet_to_payout`.

  Valid `type` values: `payment.initiated`, `payment.succeeded`,
  `payment.failed`, `order.fulfilled`, `wallet.credited`, `wallet.debited`,
  `wallet.refunded`, `payout.initiated`, `payout.succeeded`, `payout.failed`.

  Note the asymmetry: requests send `type`, event reads return `event_type`.

  ### Ingestion behavior

  `POST /v2/events` accepts 1 to 500 events, up to 5 MiB per request and 256 KiB
  per event. It returns `202` when at least one event is accepted, and `422` when
  all are rejected.

  Always read `results`. Each item has `index` matching the submitted position,
  and `status` of `accepted`, `duplicate`, or `rejected`. Rejection codes are
  `invalid_event`, `unknown_field`, `idempotency_conflict`, `duplicate`, and
  `malformed_request`.

  `accepted` means the event was stored, not that the operation succeeded.

  ### Retries

  Retry with the same `id` and the same payload, since stored events return
  `duplicate`. Reusing an `id` with different content returns
  `idempotency_conflict` and must be investigated, not retried. Events without an
  `id` are unsafe to retry.

  `Idempotency-Key` applies only to `POST /v2/issues/{issue_id}/notes`. Never send
  it on event ingestion.

  ### Security

  Never hardcode, log, or commit an API key. Never log full event payloads, note
  bodies, amounts, or customer identifiers. Log `X-Request-ID` from the response
  instead.

  ### SDKs

  - TypeScript: `@reconifyhq/sdk`, `new ReconifyClient({ apiKey })`,
    `client.ingestion.ingestMonitoringEvents({ body })`.
  - Python: `reconify-python`, `Reconify()` or `AsyncReconify()`,
    `client.ingestion.ingest_monitoring_events(batch)`.

  Both retry reads automatically and do not retry ingestion unless you opt in.
  ```
</Accordion>

Next: [Send events](/guides/api-integration) covers the batch handling and retry rules the
agent's sender has to get right.