> ## Documentation Index > Fetch the complete documentation index at: https://docs.capa.fi/llms.txt > Use this file to discover all available pages before exploring further. # 🚀 Getting Started > Crypto and fiat rails connecting users to global finance *** ## Overview Capa's API enables fintechs and platforms to integrate seamless cryptocurrency on-ramping, off-ramping, and fiat-to-fiat cross-ramp transfers. Users can exchange fiat currencies for cryptocurrencies and vice versa, or convert between different fiat currencies, with just a few simple steps. Capa currently supports MXN (Mexican Peso), DOP (Dominican Peso), USD (US Dollar), and EUR (Euro). ## Integration Flow The following steps apply to every integration regardless of which transaction types you plan to support. Sign up at [sandbox.capa.fi](https://sandbox.capa.fi), then go to **Settings > Dev Tools** and click **Generate API Key** to get your staging API key -- no onboarding required. For production, use the [partner dashboard](https://dashboard.capa.fi) and follow the same path. See the [API Key Guide](/docs/partner-api-key-generation) for details on usage and regeneration. Register your webhook URL via the [Webhook Settings](/reference/partnerwebhooksettingsv2controller_update) endpoint and implement [HMAC signature validation](/docs/step-by-step-process-for-hmac-signature-validation) to verify incoming events. See [Webhooks](/docs/how-our-webhooks-work) for retry behavior and best practices. [Create a user](/reference/userpartnercontrollerv2_createuser) with `externalUserId`, `email`, and `identifier`, then complete identity verification via [KYC link](/reference/userpartnercontrollerv2_createverificationlink), [direct KYC submission](/reference/userpartnercontrollerv2_createuserkyc), or [KYB link](/reference/userpartnercontrollerv2_generatekybverificationlink) for businesses. See the [User Creation and Verification](/docs/create-and-verify-a-user-with-capa-api) guide. For off-ramp and cross-ramp transactions, provide destination bank details inline, save them via the [Bank Accounts](/docs/bank-accounts) API, or create [Receivers](/docs/receivers) for third-party payouts. Use [Get Quote Rate](/reference/quotepartnerv2controller_getpartnerquoterate) for a real-time estimate, or [Create Quote](/reference/quotepartnerv2controller_createpartnerquote) to lock a guaranteed exchange rate for 10 seconds. Quoting works the same way across on-ramp, off-ramp, and cross-ramp transactions. For cross-ramp, use the dedicated [Cross-Ramp Quote](/reference/crossramppartnerv2controller_createpartnercrossrampquote) endpoints. With a verified user (and optionally a locked quote), create the transaction for your use case: * **On-Ramp** (fiat to crypto): [Create On-Ramp](/reference/onramppartnerv2controller_createpartneronramp) -- see the [On-Ramp Guide](/docs/on-ramp) * **Off-Ramp** (crypto to fiat): [Create Off-Ramp](/reference/offramppartnerv2controller_createpartnerofframp) -- see the [Off-Ramp Guide](/docs/off-ramp) * **Cross-Ramp** (fiat to fiat): [Create Cross-Ramp](/reference/crossramppartnerv2controller_createpartnercrossramp) -- see the [Cross-Ramp Guide](/docs/cross-ramp) To safely retry a failed or timed-out request without creating a duplicate transaction, include an `Idempotency-Key` header. See the [Idempotency Guide](/docs/idempotency). Receive real-time status updates via [Transaction Events](/docs/transaction-events) and [KYC Events](/docs/kyc-events) webhooks. You can also [list transactions](/reference/transactionpartnerv2controller_listpartnerusertransactions) or [cancel a transaction](/reference/transactionpartnerv2controller_cancelpartnertransaction) as needed. See the [Transactions Guide](/docs/transactions-1). ### How It All Fits Together ```mermaid theme={null} sequenceDiagram participant Partner participant Capa participant User Partner->>Capa: Authenticate (partner-api-key header) Partner->>Capa: Create User Partner->>Capa: Start KYC / KYB Verification User->>Capa: Complete identity verification Capa->>Partner: Webhook (VERIFIED_USER or REJECTED_KYC) Partner->>Capa: Create Quote (optional) Capa->>Partner: quoteId + locked rate (expires in 10s) Partner->>Capa: Create Transaction (on/off/cross-ramp) Capa->>Partner: Transaction details + bank/wallet info User->>Capa: Deposit fiat or send crypto Capa->>Partner: Webhook (status updates) Capa->>Partner: Webhook (COMPLETED) ``` ### Key Things to Know * **KYC before transactions** -- A user must be fully verified before you can create any transaction for them. * **Quotes are optional but short-lived** -- A locked quote expires after **10 seconds**. If no quote is used, the rate is calculated at the time of funding. * **Premium spread** -- If a `quoteId` is provided, the quote's `premiumSpread` takes precedence over any value in the transaction request. Set it when creating the quote. * **Webhook reliability** -- Return a `2xx` response promptly. Failed deliveries are retried up to 5 times. As a fallback, poll the [List Transactions](/reference/transactionpartnerv2controller_listpartnerusertransactions) or [Get KYC Details](/reference/kycpartnercontrollerv2_getuserverificationdetails) endpoints. * **Idempotency keys** -- Use the `Idempotency-Key` header on transaction-creation `POST` requests to safely retry without creating duplicates. See the [Idempotency Guide](/docs/idempotency). ### Production Readiness Checklist Before going live, make sure you have: * [ ] Webhook URL registered and [HMAC signature validation](/docs/step-by-step-process-for-hmac-signature-validation) implemented * [ ] User creation + KYC/KYB flow tested end-to-end in staging * [ ] At least one transaction of each type you support tested in staging * [ ] Error handling for common error codes (`400`, `401`, `403`, `404`, `409`, `429`) * [ ] Safeguards against duplicate submissions (no idempotency key support) * [ ] Rate limiting handled (10 requests per second per partner) ## API Environments | Environment | Base URL | Purpose | | -------------- | -------------------------------- | --------------------------------- | | **Staging** | `https://staging-api.capa.fi` | Testing and development | | **Production** | `https://production-api.capa.fi` | Live transactions with real funds | ### Staging vs Production | Aspect | Staging | Production | | ---------------- | ----------------------------------------------------------------------------------------- | ---------------------------- | | Fiat transfers | Simulated (no real money moves) | Real SPEI/ACH/SEPA transfers | | Crypto transfers | Real on-chain transactions | Real on-chain transactions | | KYC verification | Not validated (random data accepted) | Full identity verification | | Exchange rates | May differ from live market | Live market rates | | Mock testing | Enabled ([see mock guide](/reference/transactionpartnerv2controller_getmocktestingguide)) | Disabled | ### Rate Limits All API endpoints are rate-limited to **10 requests per second** per partner. Exceeding this limit returns a `429 Too Many Requests` response. Rate limit information is not included in response headers. ### Error Response Format All error responses follow this structure: ```json theme={null} { "status": "failed", "code": "INVALID_USER_INPUT", "message": "Description of what went wrong", "errors": [ { "field": "email", "message": "must be a valid email" } ] } ``` Common error codes: | HTTP Status | Code | Description | | ----------- | --------------------------- | ----------------------------------------------------- | | 400 | `INVALID_USER_INPUT` | Validation error (missing or invalid fields) | | 401 | `UNAUTHORIZED` | Invalid or missing API key | | 403 | `FORBIDDEN` | Action not allowed for this partner or user | | 404 | `NOT_FOUND` | Resource not found | | 409 | `USER_ALREADY_EXISTS_ERROR` | User with this email or externalUserId already exists | | 429 | — | Rate limit exceeded | ### Idempotency The API does not currently support idempotency keys. Sending the same request twice will create two separate resources (e.g., two transactions). Ensure your integration includes safeguards to prevent duplicate submissions. ### API Status Monitor API availability at [status.capa.fi](https://status.capa.fi). ## 🔌 Our API ### Buy and Sell Cryptocurrency Allow your users to purchase and sell digital assets such as USDC directly through our API, using supported fiat currencies including MXN, DOP, USD, and EUR. ### Cross-Border Fiat Transfers Enable your users to convert between fiat currencies (e.g., MXN to USD) without touching crypto. Capa handles the conversion and delivers funds to the target bank account. ### Instant Transfers and Fast Settlement With Capa, you can eliminate long wait times for international transfers. Our platform offers near-instant settlement for both crypto and fiat transactions, ensuring users can transact quickly and efficiently. ### Local Banking and Crypto Integration Capa provides a smooth integration between banking infrastructure and the world of cryptocurrencies. Your users will be able to deposit fiat currencies, which can be instantly converted to digital assets, and they can withdraw their crypto to fiat with ease. *** ## What's Next * [🔑 API Key Generation Guide](/docs/partner-api-key-generation) * [👤 User Creation and Verification](/docs/create-and-verify-a-user-with-capa-api) * [💎 On-Ramp Guide](/docs/on-ramp) * [💵 Off-Ramp Guide](/docs/off-ramp) * [🔄 Cross-Ramp Guide](/docs/cross-ramp) * [📣 Webhooks](/docs/how-our-webhooks-work) * [❓ FAQ](/docs/faq)