# Integrate with an AI agent

Give your coding assistant this guide and the URL of **your merchant installation**. It can inspect the supported API, build a payment integration, diagnose setup blockers, and prepare changes for you to review. Wallet signatures and sensitive operations stay under your control.

## Copy this brief

```text
Integrate my application with recv.fund.

Read https://docs.recv.fund/llms.txt first. Use
https://docs.recv.fund/llms-full.txt if you need the complete documentation.
Start at https://docs.recv.fund/agents/.

My installation origin: <https://pay.example.com>
My application/repository: <path or URL>
My intended task: <accept payments / configure testnet / diagnose a payment>
My intended network: <testnet or mainnet>

1. Read the installation's /api/v1/integration/capabilities and /api-json.
2. Use a project API key provided through a local secret manager/environment,
   never chat, source code, browser code, logs or a public URL.
3. Read /api/v1/integration/readiness with the API-Key header. Explain blockers.
   Configuration readiness is not proof of a successful payment or security audit.
4. Use decimal strings. Keep payment and payout states distinct. Never mark an
   order paid based on a browser redirect, transaction submission or OPEN webhook.
5. Implement signed webhook verification and durable, atomic deduplication.
   Reconcile payment status using my server's project key before fulfillment.
6. Use testnet first. Show exact network, currency, amount and recipient before
   any fund-moving action, and wait for my explicit authorization.
7. Do not retry ambiguous payment-creation requests automatically. invoiceID is
   not an idempotency key. Use stable Idempotency-Key values for authorized payouts.
8. Test the real application, payment confirmation, duplicate and out-of-order
   webhooks, partial payments, expiry, wrong network and revoked credentials.
9. Report implemented changes, reproducible tests, observed evidence and any
   unverified deployment or network behavior. Never claim the contracts are safe
   just because configuration or automated tests pass.
```

No product-specific agent framework or MCP server is required. Any assistant able to read documentation and call HTTPS APIs can use these contracts. An MCP transport is not currently supplied.

## Machine-readable entry points

| Resource | Purpose |
| --- | --- |
| `/llms.txt` on docs.recv.fund | Small, grouped documentation index |
| `/llms-full.txt` on docs.recv.fund | Full current documentation in one text file |
| `/agents/index.md` on docs.recv.fund | Plain Markdown version of this guide; every content page also has a `.md` export |
| `/api-json` on your installation | OpenAPI generated by the running API |
| `/api-yaml` on your installation | The same OpenAPI in YAML |
| `/api` on your installation | Interactive Swagger UI |
| `/api/v1/integration/capabilities` | Public integration capabilities and credential boundaries |
| `/api/v1/integration/readiness` | Project readiness using `API-Key`; observed evidence and configuration blockers |
| `/api/v1/project/getReadiness/{projectId}` | The dashboard readiness view using JWT and project access |

Use the installation's discovery and OpenAPI to check its actual version. An older installed image may return 404 for new readiness routes. Upgrade through the supported release process; never invent a missing route or substitute an admin credential for a project key.

## Choose a workflow

1. [Install and set up](https://docs.recv.fund/agents/installation-and-setup.md): prepare the instance and first project.
2. [Build a payment integration](https://docs.recv.fund/agents/payment-integration.md): create a checkout and fulfill a verified payment.
3. [Verify and troubleshoot](https://docs.recv.fund/agents/verification-and-recovery.md): diagnose incomplete setup, confirmation delays and webhook delivery.
4. [Security and permissions](https://docs.recv.fund/agents/security-and-permissions.md): separate credentials, transaction approval and evidence requirements.

The dashboard's **Developers → Build with your AI agent** panel produces a brief using the current installation origin and selected project, without including credentials.