Circle USYC 백서 전문

ties with Managed Payments enabled and optional otherwise. `PMT006` is not allowed. # Create a crypto payout Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/create-payout openapi/accounts.yaml post /v1/payouts Create a stablecoin payout to a recipient address. **Digital Asset Accounts:** crypto payouts are available only for custody accounts (`purpose: custody`) and are for third-party payouts only. They are not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. `source` is required: set `source.id` to the `accountId` of the end user's custody account. A master wallet source is rejected with `403`. The destination must be an address book recipient created with `clientEntityId` set to the end user who owns that account. The following table includes the supported pairs of `amount.currency` and `toAmount.currency`: | amount.currency | toAmount.currency | | --------------- | ----------------- | | USD | USD | | EUR | EUR | For Circle Inc (`CIRCLE_INC`) customers using Managed Payments, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`. # Create a recipient address Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/create-recipient-address openapi/accounts.yaml post /v1/addresses/recipient Stores an external blockchain address. # Create an SCA challenge Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/create-sca-challenge openapi/accounts.yaml post /v1/accounts/passkeys/challenges Creates a short-lived, single-use challenge (5-minute TTL) that captures the intent of a protected operation. Pass the returned `frameToken` to the DAA web SDK's `sca.approve` method to produce a signed assertion. The `intent` must exactly match the request body you will send to the protected endpoint — same fields, same values. # Create a webhook subscription Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/create-subscription openapi/accounts.yaml post /v2/notifications/subscriptions Create a webhook subscription by configuring an endpoint to receive notifications. # Create a wire bank account Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/create-wire-account openapi/accounts.yaml post /v1/banks/wires Create a bank account for wire transfers. # Transfer state change Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/custody-transfer openapi/accounts.yaml webhook custodyTransfer Sent when a stablecoin transfer changes state. A `wallet` destination is an internal transfer between subaccounts. A blockchain destination is an outbound crypto transfer. `status` is one of `pending`, `complete`, or `failed`. The payload also carries `transactionHash`, `fees`, `message`, `errorCode`, `riskEvaluation`, `policyEvaluation`, and `identities` when those values apply. # Delete a custody account group Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/delete-account-group openapi/accounts.yaml delete /v1/accounts/groups/{groupId} Soft-deletes a custody account group and hard-deletes every member assignment in a single transaction. Member accounts themselves are left untouched. Deletion is rejected for groups already soft-deleted or owned by a different entity. Responds with `200 OK` and an empty body on success. # Delete an address book recipient Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/delete-address-book-recipient openapi/accounts.yaml delete /v1/addressBook/recipients/{id} Removes an address book recipient. # Delete a recipient address Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/delete-recipient-address openapi/accounts.yaml delete /v1/addresses/recipient/{id} Deletes an external blockchain address. The recipient address must be in an 'active' or 'pending' state in order to be deleted successfully. # Delete a webhook subscription Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/delete-subscription openapi/accounts.yaml delete /v2/notifications/subscriptions/{id} Delete an existing webhook subscription. # Expire a payment intent Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/expire-payment-intent openapi/accounts.yaml post /v1/paymentIntents/{id}/expire Expires a payment intent so it no longer accepts payments. # Get an account Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-account openapi/accounts.yaml get /v1/accounts/{accountId} Retrieves a single account by `accountId`. # Get an account bank deposit Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-account-deposit openapi/accounts.yaml get /v1/accounts/deposits/{id} Returns a bank deposit by ID. # Get an account deposit address Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-account-deposit-address openapi/accounts.yaml get /v1/accounts/addresses/deposit/{id} Retrieves a specific deposit address. # Get a custody account group Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-account-group openapi/accounts.yaml get /v1/accounts/groups/{groupId} Retrieves a single custody account group by `groupId`. Returns the metadata view (`id`, `name`, `createDate`, `updateDate`) only — `approximateBalanceInUsd` and `accountsPreview` are intentionally omitted; see the list endpoint for the aggregate view. # Get an account transfer Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-account-transfer openapi/accounts.yaml get /v1/accounts/transfers/{id} Retrieves a specific transfer. For onchain activity, outbound transfers typically appear with an account source and blockchain destination, while inbound transfers typically appear with a blockchain source and account destination. # Get an account bank withdrawal Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-account-withdrawal openapi/accounts.yaml get /v1/accounts/withdrawals/{id} Retrieves a specific bank withdrawal. # Get an ACH bank account Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-achaccount openapi/accounts.yaml get /v1/banks/ach/{id} Retrieves a specific ACH bank account. # Get ACH instructions Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-achaccount-instructions openapi/accounts.yaml get /v1/banks/ach/{id}/instructions Retrieves ACH deposit instructions for a specific bank account. # Get an address book recipient Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-address-book-recipient openapi/accounts.yaml get /v1/addressBook/recipients/{id} Retrieves a specific address book recipient. # Get an FX settlement Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-fx-settlement openapi/accounts.yaml get /v1/exchange/trades/settlements/{id} Retrieves an FX settlement. # Get an FX trade Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-fx-trade openapi/accounts.yaml get /v1/exchange/trades/{id} Retrieves an FX trade. # Get a notification signature public key Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-notification-signature openapi/accounts.yaml get /v2/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`: the digital signature generated by Circle. - `X-Circle-Key-Id`: the UUID used as the `id` path parameter to retrieve the relevant public key. # Get a crypto payment Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-payment openapi/accounts.yaml get /v1/payments/{id} Retrieves a specific crypto payment or crypto refund. # Get a payment intent Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-payment-intent openapi/accounts.yaml get /v1/paymentIntents/{id} Retrieves a specific payment intent. # Get a crypto payout Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-payout openapi/accounts.yaml get /v1/payouts/{id} Retrieves a specific crypto payout. # Get a recipient address Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-recipient-address openapi/accounts.yaml get /v1/addresses/recipient/{id} Retrieves a specific recipient address. # Get a webhook subscription Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-subscription openapi/accounts.yaml get /v2/notifications/subscriptions/{id} Returns an existing webhook subscription. # Get all webhook subscriptions Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-subscriptions openapi/accounts.yaml get /v2/notifications/subscriptions Returns an array of all webhook subscriptions. # Get a wire bank account Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-wire-account openapi/accounts.yaml get /v1/banks/wires/{id} Retrieves a specific wire bank account. # Get wire instructions Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/get-wire-account-instructions openapi/accounts.yaml get /v1/banks/wires/{id}/instructions Retrieves wire transfer instructions for a specific bank account. # List all account deposit addresses Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-deposit-addresses openapi/accounts.yaml get /v1/accounts/addresses/deposit Returns a list of deposit addresses for an account. # List all account bank deposits Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-deposits openapi/accounts.yaml get /v1/accounts/deposits Searches for bank deposits sent to accounts. If the date parameters are omitted, returns the most recent deposits. This endpoint returns up to 50 deposits in descending chronological order or pageSize, if provided. # List custody account groups Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-groups openapi/accounts.yaml get /v1/accounts/groups Retrieves the custody account groups owned by the calling entity. Each row includes an aggregate USD-equivalent balance and a short preview of member account names; use the detail endpoint for metadata only. # List account limits and usage Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-limits-usage openapi/accounts.yaml get /v1/accounts/{accountId}/limits/usage Retrieves the effective limits and current usage for an account. Monetary values use USD cents, and count-based limits use whole-number counts. Transaction limits do not include `window`, `currentAggregate`, or `usagePercent`. Aggregate fields can also be omitted when a usage source is unavailable. # List all account transactions Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-transactions openapi/accounts.yaml get /v1/accounts/transactions Searches for transactions across account activity, including deposits, withdrawals, transfers and other activity. Results are returned in descending chronological order. If date parameters are omitted, returns the most recent transactions. # List all account transfers Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-transfers openapi/accounts.yaml get /v1/accounts/transfers Searches for transfers. Results include internal account-to-account transfers, onchain deposits, and onchain withdrawals. Use the `source` and `destination` fields on each transfer to determine directionality. Returns up to 50 transfers in descending chronological order or `pageSize`, if provided. If date parameters are omitted, returns the most recent transfers. # List all account bank withdrawals Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-account-withdrawals openapi/accounts.yaml get /v1/accounts/withdrawals Lists all bank withdrawals for accounts. # List all accounts Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-accounts openapi/accounts.yaml get /v1/accounts Retrieves the accounts available to the calling entity. # List all ACH bank accounts Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-achaccounts openapi/accounts.yaml get /v1/banks/ach Retrieves a list of bank accounts for ACH transfers. `clientEntityId` is the identifier returned by [Create a partner client](https://developers.circle.com/api-reference/end-user-onboarding/create-partner-client) (`POST /v1/partner/clients`). Passing the `entityId` of your own account from `GET /v1/accounts` returns `400` with error code `3027`. A well-formed `clientEntityId` that doesn't match any client returns `200` with an empty `data` array rather than `404`, so an empty list doesn't confirm that the client entity exists. # List all address book recipients Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-address-book-recipients openapi/accounts.yaml get /v1/addressBook/recipients Lists all address book recipients. # List all FX settlements Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-fx-settlements openapi/accounts.yaml get /v1/exchange/trades/settlements Lists settlements of FX trades for your end users' accounts, newest first. # List all FX trades Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-fx-trades openapi/accounts.yaml get /v1/exchange/trades Lists FX trades for your end users' accounts, newest first. Without `from` and `to`, returns trades created in the last 180 days. The `from`/`to` window is capped at 180 days, except that a `settlementId` query with no dates returns all of that settlement's trades. # List passkeys Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-passkeys openapi/accounts.yaml get /v1/accounts/passkeys Returns all passkeys registered for an end user, and whether Circle requires SCA for that end user (`sca.required`). # List all payment intents Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-payment-intents openapi/accounts.yaml get /v1/paymentIntents Lists all payment intents. # List all crypto payments Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-payments openapi/accounts.yaml get /v1/payments Lists all crypto payments and crypto refunds. # List all crypto payouts Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-payouts openapi/accounts.yaml get /v1/payouts Lists all crypto payouts. # List all recipient addresses Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-recipient-addresses openapi/accounts.yaml get /v1/addresses/recipient Returns a list of recipient addresses that have been verified and are eligible for transfers. # List all wire bank accounts Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/list-wire-accounts openapi/accounts.yaml get /v1/banks/wires Retrieves a list of bank accounts for wire transfers. `clientEntityId` is the identifier returned by [Create a partner client](https://developers.circle.com/api-reference/end-user-onboarding/create-partner-client) (`POST /v1/partner/clients`). Passing the `entityId` of your own account from `GET /v1/accounts` returns `400` with error code `3027`. A well-formed `clientEntityId` that doesn't match any client returns `200` with an empty `data` array rather than `404`, so an empty list doesn't confirm that the client entity exists. # Recipient address state change Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/mint-address-book-recipients openapi/accounts.yaml webhook mintAddressBookRecipients Sent when a recipient address changes state, most often as it moves through verification. `status` is one of `pending`, `pending_verification`, `pending_additional_information`, `pending_owner_information`, `pending_beneficiary_information`, `denied`, `inactive`, `verification_succeeded`, `active`, `on_hold`, `failed`, or `disabled`. Wait for `active` before using the address as a transfer destination. # Deposit state change Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/mint-deposits openapi/accounts.yaml webhook mintDeposits Sent when a fiat deposit into a subaccount changes state. `status` is one of `pending`, `complete`, or `failed`. # Payout terminal state Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/mint-payout openapi/accounts.yaml webhook mintPayout Sent when a withdrawal to a bank account reaches a terminal state. `status` is `complete` or `failed`. Not sent for the intermediate `pending` state. # Wire state change Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/mint-wire openapi/accounts.yaml webhook mintWire Sent when a wire transfer changes state. `status` is one of `pending`, `complete`, or `failed`. # Modify an address book recipient Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/modify-address-book-recipient openapi/accounts.yaml patch /v1/addressBook/recipients/{id} Only `metadata` can be updated. A change sends the recipient back to `pending` for a new risk review, and payouts to it fail until it is `active` again. # Open a passkey registration session Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/open-passkey-registration openapi/accounts.yaml post /v1/accounts/passkeys/registrations Creates a short-lived registration session (10-minute TTL) that coordinates WebAuthn passkey enrollment for an end user. Pass the returned `frameToken` to the DAA web SDK's `sca.enroll` method to run the enrollment ceremony. # Refund a payment intent Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/refund-payment-intent openapi/accounts.yaml post /v1/paymentIntents/{id}/refund Creates a crypto refund for a payment intent. **Digital Asset Accounts:** crypto payments are available only for custody accounts (`purpose: custody`) and are for third-party payments only. They are not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. # Resend a recipient address verification challenge Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/resend-recipient-verification-challenge openapi/accounts.yaml post /v1/addresses/recipient/{id}/verification/resend Recreates a satoshi-test verification challenge for a self-hosted recipient address that is pending verification. # Revoke a passkey Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/revoke-passkey openapi/accounts.yaml delete /v1/accounts/passkeys/{passkeyId} Soft-deletes a passkey by setting its `revokedDate`. The credential record is retained but is no longer accepted for SCA ceremonies. To re-enroll an end user after a device reset, revoke the old passkey and run the enrollment flow again. # Bulk-unassign accounts from a custody account group Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/unassign-