Stablecoin On/Off-Ramp

Convert between fiat (NGN) and stablecoins (USDC or USDT).

Open the interactive version or read this guide as markdown.

Tags: Swap, Balance, Payouts

Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io

You are helping me build a stablecoin on-ramp and off-ramp into my existing application using CoinCircuit swaps. I have the CoinCircuit MCP server connected.

If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:

• Call get_api_overview in the CoinCircuit MCP for base URLs, auth method, and available features.
• Call search_api with query swap and type endpoints to list all swap endpoints (estimate, quotation, execute, history).
• Call get_endpoint with method get and path /api/v1/swap/estimate for the indicative estimate schema.
• Call get_endpoint with method post and path /api/v1/swap/quotation for the locked-rate quotation schema.
• Call get_endpoint with method post and path /api/v1/swap/execute/{quotationId} for the execute schema.
• Call get_endpoint with method get and path /api/v1/balance for the balance response schema.
• Call get_endpoint with method post and path /api/v1/payouts for the payout (off-ramp withdrawal) schema.
• Call get_conversion_rate in the CoinCircuit MCP for live display rates.

Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP.

API Basics

• Base URL (production): https://api.coincircuit.io
• Base URL (sandbox): https://sandbox-api.coincircuit.io
• Auth: Pass your API key in the x-api-key header on every request.

Project Context

I want users to move between fiat and stablecoins held in my CoinCircuit merchant balance:

• On-ramp: fiat (NGN) -> stablecoin (USDC or USDT)
• Off-ramp: stablecoin (USDC or USDT) -> fiat (NGN), then withdraw to a bank account

Swaps convert between two currencies in your CoinCircuit balance at a rate you lock in advance. Supported balance currencies for swaps are NGN and a stablecoin (USDC or USDT). The flow is always: get a quote -> lock a quotation -> execute before it expires.

What I Need You to Implement

1. Check the balance

Endpoint: GET /api/v1/balance?currency={currency} (Call get_endpoint with method get, path /api/v1/balance in the CoinCircuit MCP for the full response schema.)

• currency (optional) - "NGN" or your stablecoin ("USDC" or "USDT"). If omitted, returns your default currency balance.

Confirm availableBalance covers the amount you intend to swap before requesting a quotation.

2. Get an indicative estimate (optional)

Show the user roughly what they'll get before committing. This rate is indicative only, not locked.

Endpoint: GET /api/v1/swap/estimate?fromCurrency={from}&toCurrency={to}&amount={amount} (Call get_endpoint with method get, path /api/v1/swap/estimate in the CoinCircuit MCP for the full response schema.)

Query params:

• fromCurrency - "NGN" or your stablecoin ("USDC" or "USDT")
• toCurrency - the other side
• amount (string) - amount to swap, up to 2 decimal places, e.g. "100.00"

Response (200): fromCurrency, toCurrency, sourceAmount, targetAmount, rate.

Example: on-ramp 100,000 NGN into a stablecoin, or off-ramp 100.00 USDC/USDT into NGN.

3. Create a locked quotation

When the user commits, lock the rate.

Endpoint: POST /api/v1/swap/quotation (Call get_endpoint with method post, path /api/v1/swap/quotation, section request in the CoinCircuit MCP for the exact request body.)

Request body:

{
  "fromCurrency": "USDC",
  "toCurrency": "NGN",
  "amount": "100.00"
}

Response (201): Returns the quotation:

• data.id - the quotation ID (pass this to execute)
• data.fromCurrency / data.toCurrency
• data.sourceAmount / data.targetAmount
• data.rate - the locked rate
• data.expiresAt - the quotation expires within seconds. Execute promptly.
• data.executed - false until executed

(Call get_endpoint with method post, path /api/v1/swap/quotation, section success in the CoinCircuit MCP for the full response schema.)

4. Execute the swap

Endpoint: POST /api/v1/swap/execute/{quotationId} (Call get_endpoint with method post, path /api/v1/swap/execute/{quotationId} in the CoinCircuit MCP for the full schema.)

No request body. Pass the quotationId from step 3 in the path. CoinCircuit atomically debits the source currency and credits the target currency at the locked rate.

Response (200): Returns the completed swap:

• data.id - swap ID
• data.fromCurrency / data.toCurrency
• data.sourceAmount / data.targetAmount
• data.rate
• data.status - "completed"
• data.completedAt

Errors: 400 (quotation expired, already used, or insufficient balance), 404 (quotation not found).

5. Withdraw fiat to a bank account (complete the off-ramp)

After swapping a stablecoin into NGN, move the NGN out to a bank account.

Endpoint: POST /api/v1/payouts with method: "fiat" (Call get_endpoint with method post, path /api/v1/payouts in the CoinCircuit MCP for the request body and the bank-account recipient setup.)

Fiat payouts settle to the merchant's own registered bank account. Track them with payout.success / payout.failed webhooks.

6. Review swap history

• List: GET /api/v1/swaps (paginated)
• Get one: GET /api/v1/swaps/{id}

(Call get_endpoint with method get, path /api/v1/swaps in the CoinCircuit MCP for pagination params and the response schema.)

Ramp Flow Summary

On-ramp:  Bank transfer -> NGN balance -> POST /swap/quotation (NGN -> USDC/USDT) -> POST /swap/execute -> stablecoin balance
Off-ramp: Stablecoin balance -> POST /swap/quotation (USDC/USDT -> NGN) -> POST /swap/execute -> NGN balance -> POST /payouts (fiat) -> bank

Constraints

• Supported swap currencies are NGN and a stablecoin (USDC or USDT). amount is a string with up to 2 decimal places (e.g. "100.00").
• The estimate is a preview only. The rate is locked when you create a quotation.
• Quotations expire within seconds. Create the quotation immediately before executing, and handle the "expired" error by re-quoting.
• A quotation can only be executed once. Re-executing a used quotation returns a 400.
• Show users the targetAmount from the quotation. That is the exact amount they receive at the locked rate.
• Always check availableBalance for the source currency before quoting.