# Build with an AI agent

If you are integrating with an agent in the loop, give it the real documentation rather than letting it guess from training data. Everything below is machine-readable and public.

## The three URLs worth knowing

| URL | What it is | Use it for |
| --- | --- | --- |
| [`/llms.txt`](https://docs.kwiknkap.com/llms.txt) | A map of this site, with a link to every page | Letting an agent find the right page |
| [`/llms-full.txt`](https://docs.kwiknkap.com/llms-full.txt) | Every page's markdown, in one file | Dropping the whole corpus into context |
| [`/openapi.json`](https://api.kwiknkap.com/v1/openapi.json) | The OpenAPI 3 description of every endpoint | Generating clients, and calling the API |

Any page also has a markdown source: append `.md` to its URL. `…/en/concepts/idempotency.md` gives you the source of that page with no navigation, no HTML and no scraping.

Each page carries **Open in Claude** and **Open in ChatGPT** buttons, which hand the assistant that markdown directly.

## Claude Code, Codex and other CLIs

The fastest useful thing is to put the map in your project so the agent reads it on demand rather than being reminded each time.

```bash
# Fetch once, commit alongside your integration.
curl -o docs/kwiknkap-llms.txt https://docs.kwiknkap.com/llms.txt
```

Then in your `CLAUDE.md`, `AGENTS.md` or equivalent:

```markdown
## Kwik Nkap integration

The API reference is at https://docs.kwiknkap.com/llms.txt — fetch the
relevant page before changing payment code.

Non-negotiables for this codebase:
- A 201 from POST /v1/payments means PENDING, never paid. Only fulfil on
  a transition into SUCCESS.
- Every POST carries an Idempotency-Key generated once per operation.
- Never log or commit a kn_sk_live_ key.
```

Those three rules are the ones agents most often get wrong, because a card-payment mental model is far better represented in training data than a Mobile Money one. Stating them explicitly costs four lines and saves a class of bug — see [How a payment works](/en/concepts/how-payments-work) for why.

## MCP and connectors

**Coming soon.** What we are building is a connector you add to Claude or ChatGPT once, after which you can say "raise an invoice for Awa, 25 000 XAF, due Friday" or "give me a payment link for 5 000" and get back a real link to send. Sandbox by default, with anything that moves money asking first.

Until that ships, our OpenAPI description works with the general OpenAPI-to-MCP bridges, which expose each endpoint as a tool:

```jsonc
// Example shape — check your bridge's own docs for exact keys.
{
  "mcpServers": {
    "kwiknkap": {
      "command": "npx",
      "args": ["-y", "<an-openapi-mcp-bridge>", "https://api.kwiknkap.com/v1/openapi.json"],
      "env": { "API_KEY": "kn_sk_test_..." }
    }
  }
}
```

**Use a sandbox key.** An agent with a `kn_sk_live_` key can move real money on its own initiative, and "I did not expect it to actually charge someone" is not a recoverable position. If you must point one at live, mint a key [scoped](/en/concepts/scopes) to `payments:read` so it can look but not touch.

## Writing prompts that produce correct code

Three things to state, because an agent will otherwise assume the opposite:

**"Payments are asynchronous."** Without it you get code that reads `response.status` and ships the order. See [Payment states](/en/concepts/payment-states).

**"Amounts are whole XAF, minimum 100, no minor units."** Most payment training data is cents-based, so agents multiply by 100 unprompted.

**"Handle failures with `failure_code`, not by parsing messages."** The [codes](/en/concepts/errors) are stable and provider-independent; the messages are for humans.

## Next steps

- [How a payment works](/en/concepts/how-payments-work) — the page to give an agent first
- [Errors and failure codes](/en/concepts/errors) — the vocabulary to branch on
- [API reference](/en/api/direct-payments) — generated from the same spec your agent reads