Circle USYC 백서 전문

int page URL to see the underlying `openapi` reference in its frontmatter. </Note> # StableFX API Source: https://developers.circle.com/api-reference/stablefx Request quotes and execute institutional FX trades between supported currencies with onchain settlement on Arc. Use StableFX if you're a financial institution—a payment service provider, fintech, crypto OTC desk, or prime broker—working in Request-for-Quote (RFQ) workflows. ## Get started <CardGroup> <Card title="API keys" icon="key" href="/api-reference/keys"> Authenticate your requests with an API key. </Card> <Card title="Postman collection" icon="rocket" href="/api-reference/stablefx/postman"> Try the StableFX API with Circle's Postman collection. </Card> <Card title="Webhooks" icon="bell" href="/api-reference/stablefx/all/get-subscriptions"> Set up webhook subscriptions for trade events. </Card> </CardGroup> ## Endpoint categories <CardGroup> <Card title="Quotes" icon="tag" href="/api-reference/stablefx/all/create-quote"> Request a quote for an FX trade. </Card> <Card title="Trades" icon="right-left" href="/api-reference/stablefx/all/list-trades"> Create, list, and retrieve trades. </Card> <Card title="Signatures" icon="signature" href="/api-reference/stablefx/all/register-trade-signature"> Register and generate trade and funding signatures. </Card> <Card title="Fees" icon="receipt" href="/api-reference/stablefx/all/get-trade-fee"> Look up fees for a trade. </Card> <Card title="Funding" icon="wallet" href="/api-reference/stablefx/all/fund-trade"> Fund a trade for settlement. </Card> </CardGroup> ## OpenAPI specifications The StableFX API reference is generated from this OpenAPI specification: * `https://developers.circle.com/openapi/stablefx.yaml` See [OpenAPI Specifications](/api-reference/openapi-specifications) for the full catalog of Circle's API specs. # Cancel a settlement advance reservation Source: https://developers.circle.com/api-reference/stablefx/all/cancel-settlement-advance-reservation openapi/stablefx.yaml post /v1/exchange/stablefx/settlementAdvances/reservations/{reservationId}/cancel Cancels an active settlement advance reservation, releasing the held credit back to the line. Only reservations in `active` status can be canceled. # Contract maker delegate deliver failed Source: https://developers.circle.com/api-reference/stablefx/all/contract-maker-delegate-deliver-failed openapi/stablefx.yaml webhook contractMakerDelegateDeliverFailed The maker's delegated funding transaction failed on-chain. # Maker deliver operation failed Source: https://developers.circle.com/api-reference/stablefx/all/contract-maker-deliver-failed openapi/stablefx.yaml webhook contractMakerDeliverFailed The maker deliver operation on the contract has failed. The maker's deliver transaction failed to confirm onchain. # Record trade operation failed Source: https://developers.circle.com/api-reference/stablefx/all/contract-record-trade-failed openapi/stablefx.yaml webhook contractRecordTradeFailed The record trade operation on the contract has failed. The initial onchain recording of the trade was unsuccessful. # Contract taker delegate deliver failed Source: https://developers.circle.com/api-reference/stablefx/all/contract-taker-delegate-deliver-failed openapi/stablefx.yaml webhook contractTakerDelegateDeliverFailed The taker's delegated funding transaction failed on-chain. # Taker deliver operation failed Source: https://developers.circle.com/api-reference/stablefx/all/contract-taker-deliver-failed openapi/stablefx.yaml webhook contractTakerDeliverFailed The taker deliver operation on the contract has failed. The taker's deliver transaction failed to confirm onchain. # Create a quote Source: https://developers.circle.com/api-reference/stablefx/all/create-quote openapi/stablefx.yaml post /v1/exchange/stablefx/quotes Creates a quote for a trade between two currencies. You should provide an `amount` for the `from` parameter or the `to` parameter, but not for both. Use `type:tradable` for an executable quote or `type:reference` for an indicative quote. Tradable quotes include presign `typedData` for signing. # Create a webhook subscription Source: https://developers.circle.com/api-reference/stablefx/all/create-subscription openapi/stablefx.yaml post /v2/stablefx/notifications/subscriptions Create a webhook subscription by configuring an endpoint to receive notifications. # Create a trade Source: https://developers.circle.com/api-reference/stablefx/all/create-trade openapi/stablefx.yaml post /v1/exchange/stablefx/trades Accepts a quote and creates a trade. # Delete a notification subscription Source: https://developers.circle.com/api-reference/stablefx/all/delete-subscription openapi/stablefx.yaml delete /v2/stablefx/notifications/subscriptions/{id} Delete an existing subscription. # Fund trades Source: https://developers.circle.com/api-reference/stablefx/all/fund-trade openapi/stablefx.yaml post /v1/exchange/stablefx/fund Executes funding for trades using Permit2 signatures. This endpoint relays the signed permit data to complete the funding operation for trades. When `fundingMode` is `delegate` or `net_delegate`, the request must include the trader's delegate-funding authorization in `permit2`/`signature` along with the funder's permit in `funderPermit2`/`funderSignature`. The funder delivers the tokens on the trader's behalf; no tokens transfer from the trader. A single contract trade ID uses single-trade payloads; more than one (or any count for `net_delegate`) uses batch payloads. # Generate funding presign data Source: https://developers.circle.com/api-reference/stablefx/all/generate-funding-presign-data openapi/stablefx.yaml post /v1/exchange/stablefx/signatures/funding/presign Returns the Permit2 EIP-712 payload that the trader must sign for funding operations. `fundingMode` net and net_delegate options are supported for maker funding requests only. When `fundingMode` is `delegate` or `net_delegate`, the response instead contains two typed-data payloads: one for the trader to sign (a zero-amount authorization) and one for the funder to sign (carrying the actual delivery amount). Both require `funderAddress` and `recipientAddress`. `delegate` supports both maker and taker, and returns single-trade typed data for one contract trade ID or batch typed data for more than one. `net_delegate` is maker-only, requires every given trade to already be `taker_funded`, nets deliverables minus receivables across the given contract trade IDs into a single payment obligation, and always returns batch typed data — even for a single contract trade ID. # Generate trade presign data Source: https://developers.circle.com/api-reference/stablefx/all/generate-trade-signature-data openapi/stablefx.yaml get /v1/exchange/stablefx/signatures/presign/{tradeId} Returns the EIP-712 Permit2 payload that the maker must sign for a trade. # Get a notification signature public key Source: https://developers.circle.com/api-reference/stablefx/all/get-notification-signature openapi/stablefx.yaml get /v2/stablefx/notifications/publicKey/{id} Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle. In the headers of each webhook, you can find - `X-Circle-Signature`: a header containing the digital signature generated by Circle. - `X-Circle-Key-Id`: a header containing the UUID. This is will be used as the `ID` as URL parameter to retrieve the relevant public key. # Get settlement advance credit line Source: https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-credit openapi/stablefx.yaml get /v1/exchange/stablefx/settlementAdvances/credit Returns the maker's settlement-advance credit line including total limit, current usage, available headroom per currency, and the applicable fee schedule (recurring, draw, and reservation fees). # Get settlement advance detail Source: https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-detail openapi/stablefx.yaml get /v1/exchange/stablefx/settlementAdvances/{advanceId} Returns the full detail of a single settlement advance including its lifecycle status, advance and collateral amounts, fee information, and any repayments applied. # Get a settlement advance repayment Source: https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-repayment openapi/stablefx.yaml get /v1/exchange/stablefx/settlementAdvances/repayments/{repaymentId} Returns the details of a specific settlement advance repayment. # Get a settlement advance reservation Source: https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-reservation openapi/stablefx.yaml get /v1/exchange/stablefx/settlementAdvances/reservations/{reservationId} Returns a single settlement advance reservation by ID. # Get a notification subscription Source: https://developers.circle.com/api-reference/stablefx/all/get-subscription openapi/stablefx.yaml get /v2/stablefx/notifications/subscriptions/{id} Returns an existing notification subscription. # Get all webhook subscriptions Source: https://developers.circle.com/api-reference/stablefx/all/get-subscriptions openapi/stablefx.yaml get /v2/stablefx/notifications/subscriptions Returns an array of all webhook subscriptions. # Get a trade Source: https://developers.circle.com/api-reference/stablefx/all/get-trade-by-id openapi/stablefx.yaml get /v1/exchange/stablefx/trades/{tradeId} Returns a trade specified by the ID path parameter # Get fee for a trade Source: https://developers.circle.com/api-reference/stablefx/all/get-trade-fee openapi/stablefx.yaml get /v1/exchange/stablefx/fees/{tradeId} Returns the fee associated with the trade ID provided in the path parameter. # List settlement advance reservations Source: https://developers.circle.com/api-reference/stablefx/all/list-settlement-advance-reservations openapi/stablefx.yaml get /v1/exchange/stablefx/settlementAdvances/reservations Returns the maker's settlement advance reservations, optionally filtered by status and currency. Supports cursor-based pagination, newest first. # List settlement advances Source: https://developers.circle.com/api-reference/stablefx/all/list-settlement-advances openapi/stablefx.yaml get /v1/exchange/stablefx/settlementAdvances Returns the maker's settlement advances with their lifecycle status, filterable by status and date range. Supports cursor-based pagination. # Get all trades Source: https://developers.circle.com/api-reference/stablefx/all/list-trades openapi/stablefx.yaml get /v1/exchange/stablefx/trades Returns a cursor-paginated list of all trades, newest first by default. Pagination is navigated through the `Link` response header, not the response body. Follow the `next` relation to walk the collection and stop when it is no longer returned. **Incremental sync with `updatedFrom`/`updatedTo`:** use these parameters to fetch only trades whose status changed since your last poll. When either is provided without `from`/`to`, the service widens the create-date window to cover the full available trade history so that trades created long ago but recently updated are not silently excluded. # Get settlement advance Permit2 typed data for signing Source: https://developers.circle.com/api-reference/stablefx/all/presign-settlement-advance openapi/stablefx.yaml post /v1/exchange/stablefx/signatures/settlementAdvances/presign Returns Permit2 typed-data the maker signs to authorize delegate funding of their side of a trade. The witness is a `DelegateFundingAuthorization` with `permitted.amount = 0` -- Permit2 is used purely as an authorization carrier, no tokens transfer from the maker. Stateless: no persistence, no side effects. # Register a trade signature Source: https://developers.circle.com/api-reference/stablefx/all/register-trade-signature openapi/stablefx.yaml post /v1/exchange/stablefx/signatures Registers a signed EIP-712 payload from the trader that confirms trade intent. # Repay a settlement advance Source: https://developers.circle.com/api-reference/stablefx/all/repay-settlement-advance openapi/stablefx.yaml post /v1/exchange/stablefx/settlementAdvances/repayments Records a repayment against the credit line backing a settlement advance. Any excess would be balance of the Circle Mint account. **Rounding**: for USDC and EURC repayments, the amount should be rounded up to 2 decimal places. Other stablecoins (e.g. MXNB, QCAD, AUDF, ZARU) are not subject to rounding. Idempotent on `idempotencyKey`: replays with the same key and same amount are no-ops. # Request a settlement advance Source: https://developers.circle.com/api-reference/stablefx/all/request-settlement-advance openapi/stablefx.yaml post /v1/exchange/stablefx/settlementAdvances Submit the Permit2 signature generated from the presign endpoint along with the witness payload. Funding runs asynchronously after this call returns. Idempotent on `tradeId`: replays for the same trade either return the in-progress settlement advance or short-circuit when the trade already has a non-failed active settlement advance. Calling `/reserve` first is optional. The request body is the same whether or not a prior reservation exists. **Collateral rounding**: when the repayment is complete and collateral is released, Circle rounds the collateral amount to 2 decimal places. # Reserve settlement advance credit Source: https://developers.circle.com/api-reference/stablefx/all/reserve-settlement-advance openapi/stablefx.yaml post /v1/exchange/stablefx/settlementAdvances/reserve Holds credit so the maker can lock in a fee snapshot before requesting the settlement advance. Reservations expire after a short window (~15 minutes); after expiry the maker must reserve again. Replaying the same `idempotencyKey` returns the existing reservation. Submitting a different `idempotencyKey` while another reservation for the same currency is still active will be rejected — the maker must cancel the active reservation first before creating a new one. There is one active reservation allowed per currency. A reservation is automatically cancelled after a single settlement advance is made against it. Calling `/reserve` is optional; the maker may skip it and go straight to requesting the settlement advance. # Trade breached Source: https://developers.circle.com/api-reference/stablefx/all/trade-breached openapi/stablefx.yaml webhook tradeBreached The StableFX trade has breached its maturity date. # Trade completed Source: https://developers.circle.com/api-reference/stablefx/all/trade-completed openapi/stablefx.yaml webhook tradeCompleted The StableFX trade has been completed successfully. Both the maker and the taker have funded their side and the trade is fully settled. # Trade confirmed Source: https://developers.circle.com/api-reference/stablefx/all/trade-confirmed openapi/stablefx.yaml webhook tradeConfirmed The StableFX trade has been confirmed by the exchange. # Trade failed Source: https://developers.circle.com/api-reference/stablefx/all/trade-failed openapi/stablefx.yaml webhook tradeFailed The StableFX trade has failed. # Trade maker delegate funded Source: https://developers.circle.com/api-reference/stablefx/all/trade-maker-delegate-funded openapi/stablefx.yaml webhook tradeMakerDelegateFunded The maker leg has been funded via a delegated funder. Distinct from makerFunded so subscribers can tell direct-funded legs apart from delegate-funded legs. # Trade maker funded Source: https://developers.circle.com/api-reference/stablefx/all/trade-maker-funded openapi/stablefx.yaml webhook tradeMakerFunded The maker has funded their side of the trade. The maker's fund delivery transaction has been confirmed onchain. # Trade pending settlement Source: https://developers.circle.com/api-reference/stablefx/all/trade-pending-settlement openapi/stablefx.yaml webhook tradePendingSettlement The StableFX trade has been confirmed onchain and is awaiting funding from taker and maker. # Trade refunded Source: https://developers.circle.com/api-reference/stablefx/all/trade-refunded openapi/stablefx.yaml webhook tradeRefunded The StableFX trade has been refunded. # Trade taker delegate funded Source: https://developers.circle.com/api-reference/stablefx/all/trade-taker-delegate-funded openapi/stablefx.yaml webhook tradeTakerDelegateFunded The taker leg has been funded via a delegated funder. Distinct from takerFunded so subscribers can tell direct-funded legs apart from delegate-funded legs. # Trade taker funded Source: https://developers.circle.com/api-reference/stablefx/all/trade-taker-funded openapi/stablefx.yaml webhook tradeTakerFunded The taker has funded their side of the trade. The taker's fund delivery transaction has been confirmed onchain. # Update a notification subscription Source: https://developers.circle.com/api-reference/stablefx/all/update-subscription openapi/stablefx.yaml patch /v2/stablefx/notifications/subscriptions/{id} Update a notification subscription by configuring an endpoint to receive notifications. # Postman collection Source: https://developers.circle.com/api-reference/stablefx/postman Use Circle's Postman collection to send API requests and explore the StableFX APIs. Circle's Postman collection provides sample requests for the StableFX APIs. Run them in [Postman](https://www.postman.com/), an API client. The collection matches the layout of the [API reference](/api-reference/stablefx/all/create-quote). ## Run in Postman Select **Run in Postman** below. Choose one of the following options: * **Fork**: Copies the collection and keeps a link to the parent. * **View**: Lets you try the API without importing it. * **Import**: Copies the collection without keeping a link to Circle's copy. | Collection | Link | | :- | :- | | StableFX | [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/circle-solutions/stablefx/collection/) | ## Authorization To authorize your session, use Circle's Postman variable `apiKey` and add your API key to the `environment` or `collection` variables. See Postman's [using variables](https://learning.postman.com/docs/sending-requests/variables/) guide for details. For more information about creating an API key, see [API keys](/api-reference/keys). # StableFX API rate limits Source: https://developers.circle.com/api-reference/stablefx/rate-limits Per-entity rate limits and throttling behavior for all StableFX API endpoints. Rate limits control how many requests you can make per second to each StableFX endpoint. Limits apply per entity. Your **entity ID** is the unique identifier assigned to your organization when you register with Circle. StableFX counts requests with a **sliding window** algorithm. The window is one second long. If you send more requests than the limit allows in any rolling one-second span, the API returns an HTTP `429 Too Many Requests` response until your rate drops below the limit. <Note> If you receive a `429` response, wait briefly and retry. Use exponential delay between retries. Sending requests at the same rate extends the throttle. </Note> The following table lists the per-entity rate limits for all StableFX API endpoints. For examples of calling these endpoints, see the [taker quickstart](/stablefx/quickstarts/fx-trade-taker) and [maker quickstart](/stablefx/quickstarts/fx-trade-maker). To set up the notifications endpoint, see [Set up a webhook endpoint](/api-reference/webhook-endpoints). | Method | Endpoint | Maximum requests per second | | - | - | - | | `POST` | `/v1/exchange/stablefx/quotes` | 20 | | `POST` | `/v1/exchange/stablefx/trades` | 20 | | `GET` | `/v1/exchange/stablefx/trades` | 30 | | `GET` | `/v1/exchange/stablefx/trades/{tradeId}` | 30 | | `GET` | `/v1/exchange/stablefx/signatures/*` | 20 | | `POST` | `/v1/exchange/stablefx/signatures/