# Swap APIs Base URL: `https://indexer.blackpearlmarket.com` Swap endpoints are under `/api/v1/swaps`. Amounts are raw integer strings: USDC uses 6 decimals and PEARL-side amounts use satoshis. Internal operator endpoints and privileged mutation paths are not documented publicly. ## Settlement And Fees `usdc_amount` is the buyer-side USDC amount locked in the escrow contract. Buyers pay 0% Black Pearl Market protocol fee, while network gas still applies. `fee_bps` and `fee_recipient` describe seller-side fee metadata. Current production `fee_bps` is `200`, equal to 2%. For a 100 USDC order, the buyer locks 100 USDC, pays no buyer protocol fee, and pays network gas separately. Seller proceeds are computed by the contract during claim. ## Endpoints | Method | Path | Purpose | | ------ | --------------------------------------------------- | --------------------------------------------------------------------------------- | | `GET` | `/api/v1/swaps/stats` | Aggregate settled swap count and volume. | | `GET` | `/api/v1/swaps/bids` | Indexed bids. | | `POST` | `/api/v1/swaps/bids/{order_hash}/origin` | User-facing origin metadata for a bid. | | `GET` | `/api/v1/swaps/asks` | Ask intents. Supports `include_unfunded` where needed. | | `POST` | `/api/v1/swaps/asks` | Create an ask intent. | | `GET` | `/api/v1/swaps/asks/{ask_id}` | Return one ask. | | `GET` | `/api/v1/swaps/asks/{ask_id}/deal` | Return the deal associated with an ask. | | `POST` | `/api/v1/swaps/asks/{ask_id}/take` | Buyer takes an ask and creates or associates an EVM deal. | | `GET` | `/api/v1/swaps/deals` | Return deals. | | `GET` | `/api/v1/swaps/deals/{deal_hash}` | Return one deal. | | `POST` | `/api/v1/swaps/deals/{deal_hash}/accept-lock` | Submit Pearl lock metadata. Use official app, bot, or wallet flows when possible. | | `POST` | `/api/v1/swaps/deals/{deal_hash}/verify-lock` | Verify submitted Pearl lock. | | `POST` | `/api/v1/swaps/deals/{deal_hash}/verify-refund` | Verify Pearl-side refund. | | `POST` | `/api/v1/swaps/deals/{deal_hash}/verify-evm-refund` | Verify EVM-side refund state. | Compatibility routes include `GET /api/v1/swaps/{order_hash}`, `GET /api/v1/swaps/address/{address}`, and `POST /api/v1/swaps/verify-lock/{order_hash}`. ## Ask Create Fields | Field | Required | Description | | ---------------------------------------------------------------------------- | -------- | ------------------------------------ | | `seller_pearl_address` | Yes | Seller Pearl address. | | `seller_pearl_pubkey` | Yes | Seller Pearl public key. | | `seller_evm` | Yes | Seller EVM address. | | `pearl_amount_sat` | Yes | PEARL amount in satoshis. | | `usdc_amount` | Yes | Buyer-side USDC amount in raw units. | | `expiry` | Yes | Ask expiry timestamp. | | `seller_evm_signature` | Yes | Seller EVM signature over ask terms. | | `fee_bps`, `fee_recipient`, `nonce`, `settlement_mode`, `seller_post_source` | No | Optional metadata used by app flows. | Common ask errors include `ASK_SELLER_SIGNATURE_INVALID`, `ASK_BELOW_MIN_USDC`, `ASK_INSUFFICIENT_SELLER_BALANCE`, `INDEXER_NOT_SYNCED`, and `BALANCE_UNAVAILABLE`. ## Ask Take Fields | Field | Required | Description | | ----------------------------------------------------- | -------- | ----------------------------------------------- | | `buyer_evm` | Yes | Buyer EVM address. | | `buyer_pearl_address` | Yes | Buyer Pearl address. | | `buyer_pearl_pubkey` | Yes | Buyer Pearl public key. | | `hashlock` | Yes | Hashlock for the swap. | | `pearl_refund_time` | Yes | Pearl refund timestamp. | | `evm_refund_time` | Yes | EVM refund timestamp. | | `evm_order_hash`, `fee_bps`, `fee_recipient`, `nonce` | No | Optional metadata copied or linked by the flow. | Common take errors include `ASK_NOT_FOUND`, `ASK_PAUSED`, `ASK_BUYER_PEARL_PUBKEY_MISMATCH`, `ASK_SELLER_PEARL_PUBKEY_MISMATCH`, and `CANONICAL_DEAL_NOT_FOUND`. ## PEARL HTLC Settlement Fields The public swap lifecycle exposes enough state for apps and integrators to follow PEARL-side settlement without exposing private infrastructure details. | Field | Description | | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `order_hash` or `deal_hash` | Public identifier linking API state, EVM escrow state, and PEARL-side settlement. | | `buyer_pearl_address` and `buyer_pearl_pubkey` | Known buyer PEARL destination used for release verification. | | `seller_pearl_address` and `seller_pearl_pubkey` | Seller PEARL identity used for lock and refund behavior. | | `hashlock` | Commitment for the wallet-secured secret. | | `pearl_lock_txid` and `pearl_lock_vout` | Taproot lock transaction outpoint. | | `pearl_claim_txid` | Taproot release transaction, when available. | | `pearl_refund_txid` | PEARL refund transaction, when available. | | `pearl_release_verified` | Indicates whether PEARL release proof has been verified. | | `pearl_release_verify_error` | Public verification reason when release proof is not accepted. | | `secret_hex` | Secret after it becomes part of the settlement proof. Treat as protocol-sensitive data and use official flows. | | `status` | Current lifecycle state, such as PEARL locked, USDC claimable, settled, or refunded. | Public API consumers should treat implementation-specific transaction metadata as verification data, not as a request to manually craft transactions in a browser. Use Pearl Wallet, the OTC Web App, or the Telegram Bot for signing flows when possible. ## Example Rows Bid: ```json { "order_hash": "0x...", "buyer_evm": "0x1f59...", "usdc_amount": "25000000", "pearl_amount": "6100000000", "status": "BID_OPEN", "evm_bid_txid": "0x..." } ``` Deal: ```json { "deal_hash": "0x...", "buyer_evm": "0x7120...", "seller_evm": "0x1f59...", "pearl_amount_sat": "100000000", "usdc_amount": "1250000", "fee_bps": 200, "status": "USDC_LOCKED" } ``` Verification: ```json { "ok": true, "order_hash": "0x...", "verified": false, "reason": "TAPROOT_COMMITMENT_MISMATCH", "details": { "claim_script_present": true } } ``` ## Authentication And Rate Limits Public API policy is summarized in [API Reference Overview](/overview-2.md). Public users should use the web app, Telegram bot, or verified contract interaction paths for settlement actions. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.blackpearlmarket.com/overview-2/swaps.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.