Circle USYC 백서 전문

low and not picked up by any miner/validator. - The /accelerate endpoint essentially creates another transaction with the same params as the broadcasted transaction. If multiple broadcasted transactions exist, it will use the newest created one. Afterwards, OFI can sign with a higher gas fee and submit via /submit endpoint to accelerate blockchain confirmation. - Requirements for using this endpoint: - No COMPLETED transaction exist for the payment (otherwise onchain transaction has completed) - No CREATED transaction exist for the payment, otherwise OFI should sign that transaction and submit - No PENDING transaction exist for the payment, otherwise OFI should wait for transaction to be broadcasted - In another word, all existing transaction for the payment should either be FAILED (which is no longer effective) or BROADCASTED (which means they are stuck onchain and not confirmed) # Create a payment Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-payment openapi/cpn-ofi.yaml post /v1/cpn/payments Creates a payment by using the quote created previously and submitting recipient information (travel rule). The payment will remain valid if the onchain settlement occurs before settlementExpireDate. # Create a quote Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-quotes openapi/cpn-ofi.yaml post /v1/cpn/quotes Creates one or more quotes for the given source/destination parameters. Returns quotes sorted in the following order: - Ascending of `sourceAmount` if your quote is based on `destinationAmount`. - Descending of `destinationAmount` if your quote is based on `sourceAmount`. # Create a support ticket Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-support-ticket openapi/cpn-ofi.yaml post /v1/cpn/supportTickets Create transaction-related issues (for example, settlement delays, missing information, or refunds). These tickets are stored centrally in the CPN platform and routed to the appropriate party for resolution. # Create a transaction Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-transaction openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/transactions Creates an unsigned onchain transaction for a specific payment. # Create a transaction (V2) Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-transaction-v2 openapi/cpn-ofi.yaml post /v2/cpn/payments/{paymentId}/transactions Create a V2 transaction for signing # Get a payment Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-payment openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId} Returns the PII fields needed to collect to make this payment (i.e. travel rule and beneficiary account data) # Get payment configurations Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-payment-configurations-overview openapi/cpn-ofi.yaml get /v1/cpn/configurations/overview Returns the overview of supported countries, currencies, payment methods, blockchains. # Get payment requirements for a quote Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-payment-requirements openapi/cpn-ofi.yaml get /v1/cpn/payments/requirements Retrieves the PII fields needed to collect to make this payment (travel rule and beneficiary account data). # Get details of a quote Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-quote openapi/cpn-ofi.yaml get /v1/cpn/quotes/{quoteId} Retrieve details of a specific quote (e.g., re-check expiration, fees). # Get refund details Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-refund openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}/refunds/{refundId} Retrieves the full refund object associated with a specific payment. This can be used by OFIs to reconcile refund status and verify refund completion. # Get details for an RFI Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-rfi openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}/rfis/{rfiId} Retrieve details of a specific RFI for a payment. If the BFI initiates an RFI after the payment is created, the OFI will be notified via webhook. This webhook will detail what specific information the OFI needs to send. After receiving the webhook. The OFI is expected to encrypt the requested data and send it to the BFI using CPN's RFI submit endpoint. Failure to respond to an RFI will result in a failed payment. The OFI will receive webhooks with the decision based on the submitted information. # Get a transaction Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-transaction openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}/transactions/{transactionId} Retrieves a specific transaction by its ID for a given payment # Get a transaction by ID (V2) Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-transaction-v2 openapi/cpn-ofi.yaml get /v2/cpn/payments/{paymentId}/transactions/{transactionId} Get a transaction by ID # Retrieve all ofi-enabled payment routes Source: https://developers.circle.com/api-reference/cpn/cpn-platform/list-ofi-enabled-routes openapi/cpn-ofi.yaml get /v1/cpn/configurations/enabledRoutes Retrieve all ofi-enabled payment routes. # List payments Source: https://developers.circle.com/api-reference/cpn/cpn-platform/list-payments openapi/cpn-ofi.yaml get /v1/cpn/payments Returns a list of all payments that fit the specified parameters. # Get supported payment routes Source: https://developers.circle.com/api-reference/cpn/cpn-platform/list-routes openapi/cpn-ofi.yaml get /v1/cpn/configurations/routes Returns a list of route details including trade limits. This information can determine what corridors and parameters are valid for subsequent quote creation. # Submit RFI data Source: https://developers.circle.com/api-reference/cpn/cpn-platform/submit-rfi openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/rfis/{rfiId}/submit Submit encrypted RFI data to complete an RFI request from the BFI. # Submit a signed transaction for broadcast Source: https://developers.circle.com/api-reference/cpn/cpn-platform/submit-transaction openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/transactions/{transactionId}/submit Return the signed hex string of the transaction, Circle will validate the content and broadcast to the chain. # Submit a signed transaction for broadcast (V2) Source: https://developers.circle.com/api-reference/cpn/cpn-platform/submit-transaction-v2 openapi/cpn-ofi.yaml post /v2/cpn/payments/{paymentId}/transactions/{transactionId}/submit Submit a signed V2 transaction for broadcast # Upload RFI file Source: https://developers.circle.com/api-reference/cpn/cpn-platform/upload-rfi-file openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/rfis/{rfiId}/files Upload encrypted RFI file. # Error codes Source: https://developers.circle.com/api-reference/cpn/error-codes Descriptions of error codes returned by the CPN API. When an error is encountered, CPN returns an error code and a message. The following sections show an explanation of each error code returned by the API, and steps to resolve (where possible). For error response shapes and general errors that can be returned by any Circle API, see [API errors](/api-reference/errors). ## Common | Status code | Error code | Detail | Description | | - | - | - | - | | `500` | `-1` | `UNKNOWN_ERROR` | A generic response for errors that aren't properly handled. | | `400` | `2` | `API_PARAMETER_INVALID` | API request was missing parameters or had incorrect parameter types. | | `403` | `3` | `FORBIDDEN` | The client is recognized but does not have permission to access the resource. **Resolution:** Verify the IP allowlist for the API key has the correct permissions through your Circle representative. | | `401` | `4` | `UNAUTHORIZED` | The client did not provide valid authentication credentials to access the resource. **Resolution:** Verify your API key was passed as a `Bearer` token in the `Authorization` header of the API request. | | `404` | `2` | `RESOURCE_NOT_FOUND` | The requested resource could not be found. | | `400` | `2900000` | `INVALID_TENANCY_ENV` | The parameter and the environment of the API call doesn't match (for example, a testnet chain in the production environment). **Resolution:** Update the request body to use the correct parameters. | ## Quote | Status code | Error code | Detail | Description | | - | - | - | - | | `400` | `290100` | `AMOUNT_OUTSIDE_LIMIT` | The provided amount does not fall in the supported range. It either exceeds the `cryptoLimit` or `fiatLimit`. **Resolution:** Make a request to the [enabled routes endpoint](/api-reference/cpn/cpn-platform/list-ofi-enabled-routes) to determine the limits for your available routes and try your request again with a different amount. | | `400` | `290101` | `BFI_NOT_AVAILABLE` | No BFI is available for the requested route, or the available BFI is temporarily unavailable. **Resolution:** Retry your request later. If the error persists, contact Circle Support to verify that a BFI is paired with the route. | | `400` | `290102` | `ROUTE_NOT_SUPPORTED` | The route includes unsupported countries. **Resolution:** Make a request to the [enabled routes endpoint](/api-reference/cpn/cpn-platform/list-ofi-enabled-routes) to determine the routes available to your account and try your request again with different parameters. | ## Payment | Status code | Error code | Detail | Description | | - | - | - | - | | `400` | `290200` | `QUOTE_NOT_FOUND` | The provided quote ID can't be found. **Resolution:** Verify the quote ID is correct and make a new API request. | | `400` | `290201` | `QUOTE_ALREADY_IN_USE` | The provided quote ID has been used to create another payment. **Resolution:** Request a new quote and use it to create your payment. | | `400` | `290202` | `QUOTE_EXPIRED` | The quote used to request payment creation is expired. **Resolution:** Request a new quote and use it to create your payment. | | `400` | `290203` | `INVALID_SENDER_ADDRESS_BLOCKCHAIN` | The blockchain associated with `senderAddress` does not match the requested blockchain from the quote. **Resolution:** Use the same blockchain in the payment request body as the `senderAddress`. | | `400` | `290204` | `SANCTIONED_SENDER_WALLET_ADDRESS` | The provided wallet address is on sanctioned lists. | | `400` | `290205` | `PENDING_RFI_VERIFICATION` | An RFI was requested for the sender or recipient so the payment can't be created. **Resolution:** Complete the RFI for the requested information before creating another payment. | | `400` | `290206` | `RFI_REJECTED` | The given sender or receiver has a rejected RFI with the given BFI and the payment can't be completed. | | `400` | `290207` | `REQUIRED_PARAMETER_MISSING` | A required parameter is missing in the request data. **Resolution:** Check the error in the response and make a new request with the missing parameter. | | `400` | `290208` | `COMPLIANCE_INFORMATION_REJECTED` | The compliance information provided was rejected. | | `400` | `290211` | `PAYMENT_USE_CASE_MISMATCH` | The `useCase` in the payment request doesn't match the use case the quote derives from its `senderType` and `recipientType`. **Resolution:** Send the `useCase` the quote implies. `BUSINESS` and `BUSINESS` is `B2B`, `BUSINESS` and `INDIVIDUAL` is `B2C`, `INDIVIDUAL` and `BUSINESS` is `C2B`, and `INDIVIDUAL` and `INDIVIDUAL` is `C2C`. | ## Transaction | Status code | Error code | Detail | Description | | - | - | - | - | | `400` | `290300` | `ACTIVE_TRANSACTION_ALREADY_EXISTS` | The payment already has an associated active or complete transaction. **Resolution:** For payments with an existing active transaction, sign and submit the transaction instead of attempting to create a new one. | | `400` | `290301` | `BLOCKCHAIN_UNSUPPORTED` | The sender address blockchain is not supported by CPN for creating transactions. **Resolution:** Use the blockchain indicated in the quote. | | `400` | `290302` | `BLOCKCHAIN_UNSUPPORTED_FOR_V2` | The blockchain is not support for Transactions V2. **Resolution:** See [supported blockchains](/cpn/references/blockchains/supported-blockchains) for the complete list of supported blockchains. | | `400` | `290303` | `INVALID_TRANSACTION_STATUS_FOR_SUBMISSION` | The transaction provided is not in a submittable status. **Resolution:** Only submit a transaction when it is in the `CREATED` state. | | `400` | `290304` | `INVALID_PAYMENT_STATUS` | The transaction can't be submitted due to an invalid payment state. **Resolution:** Only submit a transaction when the payment is in the `CRYPTO_FUNDS_PENDING` state. | | `400` | `290305` | `PAYMENT_NOT_FOUND` | The payment ID provided in the request was not found. | | `400` | `290306` | `TRANSACTION_NOT_FOUND` | The transaction provided by the resource ID in the path was not found. | | `400` | `290307` | `SIGNED_TRANSACTION_SUBMITTED` | A signed transaction for the payment has already been submitted. **Resolution:** Wait for the transaction to reach a terminal state. | | `400` | `290308` | `PAYMENT_EXPIRED` | The payment is expired. **Resolution:** Request a new quote, then create a new payment and submit the transaction in the appropriate time frame. | | `400` | `290309` | `SIGNED_TRANSACTION_EXPIRED` | The signed transaction is expired. Solana requires that you submit signed transactions in 150 blocks (\~1 min) of signing them. **Resolution:** Create a new transaction for the same payment and sign and submit it in the appropriate time frame. | | `400` | `290310` | `NONCE_TOO_LOW` | The nonce for the signed transaction is lower than the current wallet nonce. **Resolution:** Resubmit the signed transaction with the current wallet nonce. | | `400` | `290311` | `SIGNED_TRANSACTION_PAYLOAD_MISMATCH` | The signed transaction payload does not match the CPN payment. For EVM chains, the EIP-3009 typed data must match the value in the `messageToBeSigned` field returned from the [create transaction endpoint](/api-reference/cpn/cpn-platform/create-transaction). For Solana, the signed transaction object must match the value from the `messageToBeSigned` field. **Resolution:** Resubmit the transaction with the correct payload. | | `400` | `290312` | `INSUFFICIENT_TOKEN_BALANCE` | The sender's wallet does not have enough USDC to complete the transfer. **Resolution:** Add USDC to the wallet and resubmit the signed transaction. | | `400` | `290313` | `INSUFFICIENT_GAS_BALANCE` | The sender's wallet does not have enough native tokens to cover the gas cost of the transaction. **Resolution:** Add native tokens to the wallet and resubmit the signed transaction. | | `400` | `290314` | `PAYMENT_ID_MISMATCH` | The payment ID provided in the signed data does not match the expected value. | | `400` | `290315` | `GAS_PRICE_TOO_LOW` | The gas price in the signed transaction does not meet network thresholds. The fee must exceed the estimated high fee to ensure prompt confirmation. **Resolution:** Sign the transaction with a higher gas price and resubmit. | | `400` | `290316` | `NONCE_MISMATCH` | When resubmitting the transaction, the wallet address or nonce does not match the original submission. Sign the transaction with the same wallet and nonce as the previous transaction and resubmit. | | `500` | `290317` | `FULL_NODE_SERVICE_UNAVAILABLE` | The full node used by CPN is unavailable or returning an unexpected error during transaction validation. **Resolution:** Submit the signed transaction at a later time. | | `400` | `290318` | `PAYMENT_REF_ID_ONCHAIN` | The payment ref ID has already been used onchain. The signed transaction may have been rebroadcast prior to submission to CPN. **Resolution:** Contact Circle customer support to reconcile the transaction. | | `400` | `290319` | `OUT_OF_GAS` | For EVM chains, the gas limit in the signed transaction is insufficient to cover the execution costs. For Solana, the allocated compute budget falls short of the transaction's requirements, preventing execution. **Resolution:** For EVM chains, increase the gas limit. For Solana, increase the compute budget. Create a new transaction for the same payment and sign and submit it. | | `400` | `290320` | `NONCE_ALREADY_USED` | The nonce has already been used by the same sender in another signed transaction submission. **Resolution:** Resubmit the signed transaction using the next available nonce. | | `400` | `290321` | `INVALID_TRANSACTION_SIGNATURE` | The transaction signature is invalid. **Resolution:** Review the guidelines for signing a transaction and try again with updated signing functions. | | `400` | `290322` | `SANCTIONED_WALLET_ADDRESS` | The wallet address used is on a sanction list. | | `400` | `290324` | `CROSS_CHAIN_UNSUPPORTED` | The crosschain transfer is not supported by CPN. **Resolution:** Make a request to the [enabled routes endpoint](/api-reference/cpn/cpn-platform/list-ofi-enabled-routes) to determine the routes available to your account and try your request again with different parameters. | | `400` | `290325` | `COMPLETED_TRANSACTION_EXISTS` | A completed transaction already exists. No need to accelerate. | | `400` | `290327` | `INVALID_SIGNED_TX` | The signed transaction can't be decoded or is otherwise invalid. **Resolution:** Review the guidelines for signing a transaction and try again with updated signing functions. | | `400` | `290328` | `ONCHAIN_ACCOUNT_NOT_FOUND` | The Solana account specified in the transaction is not found. **Resolution:** Ensure the Solana account has been initialized before using it as the sender address for the transaction. | | `400` | `290329` | `TRANSACTION_EXPIRED` | The transaction is expired. **Resolution:** Create a new transaction and submit it in the appropriate time frame. | | `400` | `290330` | `CREATED_PENDING_TRANSACTION_EXIST_AT_ACCELERATION` | The existing transaction is not signed or submitted yet before the current attempt to accelerate it. **Resolution:** Sign the existing transaction or wait for the signed transaction to be broadcast. | | `400` | `290331` | `NO_TRANSACTION_TO_ACCELERATE` | No broadcast transaction to be accelerated. | | `400` | `290332` | `ONCHAIN_ACCOUNT_INVALID` | An invalid Solana address was used to create the transaction. **Resolution:** Verify the sender account provided in the request is a valid Solana address capable of signing and sending transactions. Don't use system accounts or program accounts. Resubmit the request using a valid Solana account. | | `400` | `290333` | `BROADCASTING_IN_PROGRESS` | A submitted transaction is already in a non-terminal state. **Resolution:** Wait for the result. | | `400` | `290334` | `NONCE_TOO_HIGH` | The transaction nonce exceeds the permitted range relative to the current nonce. **Resolution:** Check your wallets latest nonce and make sure the nonce selected for your transaction does not exceed that value by more than 32. If you are sending multiple concurrent transactions for multiple payments, try waiting for the previous few transactions to settle. | | `400` | `290336` | `INCOMPATIBLE_QUOTE` | The quote is incompatible with the specified transaction. The quote's `transactionVersion` must match the transaction flow you use. **Resolution:** Make sure the `transactionVersion` specified in the [endpoint response](/api-reference/cpn/cpn-platform/create-quotes) is consistent with the transaction flow you are using. | | `400` | `290337` | `PAY