bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 10쪽
circle.com/api-reference/circle-mint/payments/get-payment-customer-wallet
openapi/payments.yaml get /v1/payments/customers/{customerId}/wallets/{id}
# Get a payment intent
Source: https://developers.circle.com/api-reference/circle-mint/payments/get-payment-intent
openapi/payments.yaml get /v1/paymentIntents/{id}
# List crypto payment customer wallets
Source: https://developers.circle.com/api-reference/circle-mint/payments/list-payment-customer-wallets
openapi/payments.yaml get /v1/payments/customers/{customerId}/wallets
# List crypto payment customers
Source: https://developers.circle.com/api-reference/circle-mint/payments/list-payment-customers
openapi/payments.yaml get /v1/payments/customers
Lists Travel Rule customers for eligible Circle Singapore (`CIRCLE_SG`) merchants. List responses omit customer PII.
# List all payment intents
Source: https://developers.circle.com/api-reference/circle-mint/payments/list-payment-intents
openapi/payments.yaml get /v1/paymentIntents
# List all payments
Source: https://developers.circle.com/api-reference/circle-mint/payments/list-payments
openapi/payments.yaml get /v1/payments
# Refund a payment intent
Source: https://developers.circle.com/api-reference/circle-mint/payments/refund-payment-intent
openapi/payments.yaml post /v1/paymentIntents/{id}/refund
# Cancel recipient verification
Source: https://developers.circle.com/api-reference/circle-mint/payouts/cancel-address-book-recipient-verification
openapi/payouts.yaml post /v1/addressBook/recipients/{id}/verification/cancel
Cancels the pending verification session for a self-hosted wallet address book recipient.
This endpoint is only available for Singapore (CIRCLE_SG) entities. The recipient must have `ownership.custody.type` of `self_hosted` and be in `pending_verification` status (canceling does not change this status). After cancellation, you can either call `POST /v1/addressBook/recipients/{id}/verification/resend` to start a new verification, or `DELETE /v1/addressBook/recipients/{id}` to remove the address.
Returns 400 if the session is not cancelable (already canceled, expired, or verification already succeeded).
# Create a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/create-address-book-recipient
openapi/payouts.yaml post /v1/addressBook/recipients
Creates an address book recipient. Required fields depend on your Circle entity; use the request body options that match your integration.
For Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry, `metadata.email` is required and the beneficiary PII object matching `identity.type` (`identity.individual` or `identity.business`) is required. The two PII objects are mutually exclusive. For non-regulated jurisdictions the PII objects are accepted if provided but not required.
Validation failures can return error codes in the `2024`–`2038` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing, `2038` when `metadata.email` is missing for a self-hosted entry), as well as the PII-missing errors `ADDRESS_BOOK_INDIVIDUAL_PII_MISSING` and `ADDRESS_BOOK_BUSINESS_PII_MISSING`.
# Create a payout
Source: https://developers.circle.com/api-reference/circle-mint/payouts/create-payout
openapi/payouts.yaml post /v1/payouts
Create a stablecoin payout.
The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts:
| amount.currency | toAmount.currency |
| ---------------- | ----------------- |
| USD | USD |
| EUR | EUR |
Required fields depend on your Circle entity; use the request body options that match your integration.
For Singapore (CIRCLE_SG) entities and 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`.
# Delete a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/delete-address-book-recipient
openapi/payouts.yaml delete /v1/addressBook/recipients/{id}
# Get a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/get-address-book-recipient
openapi/payouts.yaml get /v1/addressBook/recipients/{id}
# Get a payout
Source: https://developers.circle.com/api-reference/circle-mint/payouts/get-payout
openapi/payouts.yaml get /v1/payouts/{id}
# Get a payout RFI
Source: https://developers.circle.com/api-reference/circle-mint/payouts/get-payout-rfi
openapi/payouts.yaml get /v1/payouts/{id}/rfi
Retrieves the active Request for Information (RFI) for the specified fiat payout.
An RFI is issued when the compliance team requires additional information before
the payout can proceed. Check the `fieldRequirements.schema` to determine which
fields must be submitted via `POST /v1/payouts/{id}/rfi/submit`.
# List all recipients
Source: https://developers.circle.com/api-reference/circle-mint/payouts/list-address-book-recipients
openapi/payouts.yaml get /v1/addressBook/recipients
# List VASPs
Source: https://developers.circle.com/api-reference/circle-mint/payouts/list-address-book-vasps
openapi/payouts.yaml get /v1/addressBook/vasps
Returns active Virtual Asset Service Providers (VASPs) available for the customer's jurisdiction. Use returned `id` values as `vaspId` in `ownership.custody` when creating a recipient and custody is `hosted`.
**Note:** This operation is supported only for Circle Singapore (SG) and Circle France (FR) customers.
# List all payouts
Source: https://developers.circle.com/api-reference/circle-mint/payouts/list-payouts
openapi/payouts.yaml get /v1/payouts
# Modify a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/modify-address-book-recipient
openapi/payouts.yaml patch /v1/addressBook/recipients/{id}
Updates address book recipient metadata.
# Resend recipient verification email
Source: https://developers.circle.com/api-reference/circle-mint/payouts/resend-address-book-recipient-verification
openapi/payouts.yaml post /v1/addressBook/recipients/{id}/verification/resend
Resends the verification email for a self-hosted wallet address book recipient.
This endpoint is only available for Singapore (CIRCLE_SG) entities. The recipient must have `ownership.custody.type` of `self_hosted` and be in `pending_verification` status.
Returns error code `2046` (`VERIFICATION_ADDRESS_STATE_INVALID`) if the address is not in `pending_verification` state.
# Submit a payout RFI response
Source: https://developers.circle.com/api-reference/circle-mint/payouts/submit-payout-rfi
openapi/payouts.yaml post /v1/payouts/{id}/rfi/submit
Submits the information requested by an active RFI for the specified fiat payout.
Use `GET /v1/payouts/{id}/rfi` first to retrieve the `fieldRequirements.schema`,
which defines the required keys and their validation rules.
After a successful submission the RFI transitions to `IN_REVIEW` status. The payout
resumes processing once the compliance team approves the submitted information.
# Upload a payout RFI file
Source: https://developers.circle.com/api-reference/circle-mint/payouts/upload-payout-rfi-files
openapi/payouts.yaml post /v1/payouts/{id}/rfi/files
Uploads a file in response to an active RFI file requirement for the specified fiat payout.
The `fileKey` in `fileMetadata` must match one of the `fileKey` values from the
`fileRequirements` array returned by `GET /v1/payouts/{id}/rfi`.
**Encryption** — required for BFI-generated RFIs, optional for internally-generated RFIs:
Check whether `GET /v1/payouts/{id}/rfi` returns a non-null `certificate` field:
- **`certificate` present** (BFI-generated RFI): encrypt the file client-side before upload.
1. Extract `certificate.jwk` — an EC public key in JWK format.
2. Generate a random AES-128 key and encrypt the file bytes using **AES-128-GCM**. Retain the IV.
3. Wrap the AES-128 key using **ECDH-ES + AES-128 Key Wrap** (`ECDH-ES+A128KW` / `A128GCM`)
against the EC public key from step 1. This produces a **Compact JWE string**
(`header.encryptedKey.iv.ciphertext.tag`).
4. Submit with all three multipart fields (`fileMetadata`, `encryption`, `encryptedFile`).
- **`certificate` absent** (internally-generated RFI): omit `encryption` and `encryptedFile`.
Submit only `fileMetadata` and the raw `file` field. The file is stored with standard
encryption-at-rest; no client-side encryption step is needed.
# Postman collection
Source: https://developers.circle.com/api-reference/circle-mint/postman
Use Circle's Postman collection to send API requests and explore the Circle Mint APIs.
Circle's Postman collection provides sample requests for the Circle Mint APIs.
Run them in [Postman](https://www.postman.com/), an API client. The collection
matches the layout of the
[API reference](/api-reference/circle-mint/general/ping).
## 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 |
| :- | :- |
| API Overview | [](https://app.getpostman.com/run-collection/21445022-e6b3ea60-0ff0-4919-9a58-eaf262989f82?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D21445022-e6b3ea60-0ff0-4919-9a58-eaf262989f82%26entityType%3Dcollection%26workspaceId%3D791ff53c-d236-499c-89ea-307d24ddd289) |
| Core Functionality | [](https://app.getpostman.com/run-collection/21445022-3e1635b1-7620-4001-998d-3b3aebbfc44f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D21445022-3e1635b1-7620-4001-998d-3b3aebbfc44f%26entityType%3Dcollection%26workspaceId%3D791ff53c-d236-499c-89ea-307d24ddd289) |
| Crypto Deposits API | [](https://app.getpostman.com/run-collection/21445022-27cbac71-8b44-4d50-9c83-7e39a90a7325?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D21445022-27cbac71-8b44-4d50-9c83-7e39a90a7325%26entityType%3Dcollection%26workspaceId%3D791ff53c-d236-499c-89ea-307d24ddd289) |
| Crypto Payouts API | [](https://app.getpostman.com/run-collection/21445022-53206224-cf33-4bbd-8e8a-09d5a780795a?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D21445022-53206224-cf33-4bbd-8e8a-09d5a780795a%26entityType%3Dcollection%26workspaceId%3D791ff53c-d236-499c-89ea-307d24ddd289) |
## 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).
# Create daily custody balance report
Source: https://developers.circle.com/api-reference/circle-mint/reserve-management/report-daily-custody-balances
openapi/reserve-management.yaml post /v2/reserveManagement/dailyCustodyBalances
Creates a daily custody balance report for USDC and EURC and sends it to Circle.
For `reportType=eea`, this endpoint represents the four reportable cells of EBA Template S 08.00 for one token and one reference date: CASP total token count and EUR value, plus the EU-client subset token count and EUR value.
MiCA / EBA S 08.00 mapping (`reportType=eea`):
- S 08.00 Row 0010 / Col 0010 maps to `additionalFields.totalBalance`
- S 08.00 Row 0010 / Col 0020 maps to `additionalFields.equivalentEuroTotalBalance`
- S 08.00 Row 0020 / Col 0010 maps to `localBalance`
- S 08.00 Row 0020 / Col 0020 maps to `additionalFields.equivalentEuroLocalBalance`
`localBalance` and `totalBalance` are token-unit counts. `equivalentEuroLocalBalance` and `equivalentEuroTotalBalance` are EUR values. EU clients are determined by habitual residence for natural persons and registered office for legal persons. USD/EUR FX conversion should be based on the ECB rate applicable for that date, as available on the ECB website.
Validation rules:
- `localBalance` must be less than or equal to `additionalFields.totalBalance`
- `equivalentEuroLocalBalance` must be less than or equal to `equivalentEuroTotalBalance`
- Only one submission per day per currency
- USDC and EURC require separate submissions
# Contracts API
Source: https://developers.circle.com/api-reference/contracts
Deploy and interact with smart contracts using Circle's managed infrastructure, including event monitoring and contract templates.
Smart Contract Platform lets you ship onchain logic without writing deploy
scripts, running your own indexer, or building tooling around contract calls.
## 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/contracts/postman">
Try the Contracts API with Circle's Postman collection.
</Card>
<Card title="Webhooks" icon="bell" href="/api-reference/contracts/common/get-subscriptions">
Set up webhook subscriptions for contract events.
</Card>
</CardGroup>
## Endpoint categories
<CardGroup>
<Card title="Templates" icon="file-code" href="/api-reference/contracts/smart-contract-platform/estimate-contract-template-deploy">
Deploy ERC-20, ERC-721, and ERC-1155 contracts from prebuilt templates.
</Card>
<Card title="Deploy / Import" icon="upload" href="/api-reference/contracts/smart-contract-platform/import-contract">
Deploy custom bytecode or import existing contracts.
</Card>
<Card title="View / Update" icon="list" href="/api-reference/contracts/smart-contract-platform/list-contracts">
List, retrieve, and update managed contracts.
</Card>
<Card title="Interact" icon="bolt" href="/api-reference/contracts/smart-contract-platform/query-contract">
Query contract state and submit transactions.
</Card>
<Card title="Event Monitors" icon="radar" href="/api-reference/contracts/smart-contract-platform/get-event-monitors">
Subscribe to onchain events and read event logs.
</Card>
</CardGroup>
## OpenAPI specifications
The Contracts API reference is generated from these OpenAPI specifications:
* `https://developers.circle.com/openapi/configurations_2.yaml`
* `https://developers.circle.com/openapi/smart-contract-platform.yaml`
See [OpenAPI Specifications](/api-reference/openapi-specifications) for the full
catalog of Circle's API specs.
# Challenge notification
Source: https://developers.circle.com/api-reference/contracts/common/challenges-initialize
openapi/configurations_2.yaml webhook challengesInitialize
Sent when a user-controlled wallet challenge changes state. The lifecycle
state of the challenge is conveyed by the `state` field on the
`notification` object.
States covered by this notification type:
- `COMPLETE`: the end user successfully passed the challenge. The
associated operation is initiated automatically.
- `FAILED`: the challenge failed (for example, an incorrect PIN or an
expired challenge). The operation must be re-initiated.
# Create a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/create-subscription
openapi/configurations_2.yaml post /v2/notifications/subscriptions
Create a notification subscription by configuring an endpoint to receive notifications. For details, see the [Notification Flows](https://developers.circle.com/wallets/webhook-notification-flows) guide.
# Delete a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/delete-subscription
openapi/configurations_2.yaml delete /v2/notifications/subscriptions/{id}
Delete an existing subscription.
# Get a notification signature public key
Source: https://developers.circle.com/api-reference/contracts/common/get-notification-signature
openapi/configurations_2.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
1. `X-Circle-Signature`: a header containing the digital signature generated by Circle.
2. `X-Circle-Key-Id`: a header containing the UUID. This value is used as the `ID` URL parameter to retrieve the relevant public key.
# Retrieve a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/get-subscription
openapi/configurations_2.yaml get /v2/notifications/subscriptions/{id}
Retrieve an existing notification subscription.
# Get all notification subscriptions
Source: https://developers.circle.com/api-reference/contracts/common/get-subscriptions
openapi/configurations_2.yaml get /v2/notifications/subscriptions
Retrieve an array of existing notification subscriptions.
# Ping
Source: https://developers.circle.com/api-reference/contracts/common/ping
openapi/configurations_2.yaml get /ping
Checks that the service is running.
# Inbound transaction notification
Source: https://developers.circle.com/api-reference/contracts/common/transactions-inbound
openapi/configurations_2.yaml webhook transactionsInbound
Sent when an inbound transaction changes state. The lifecycle state of the
transaction is conveyed by the `state` field on the `notification` object.
States covered by this notification type:
- `CONFIRMED`: the transaction has been broadcast onchain and is awaiting
the required number of confirmations.
- `COMPLETE`: the transaction has reached the required confirmations and
the funds are available in the destination account.
# Outbound transaction notification
Source: https://developers.circle.com/api-reference/contracts/common/transactions-outbound
openapi/configurations_2.yaml webhook transactionsOutbound
Sent when an outbound transaction changes state. The lifecycle state of
the transaction is conveyed by the `state` field on the `notification`
object.
States covered by this notification type:
- `QUEUED`: the transaction has been initiated but has not yet been
processed.
- `SENT`: the transaction has been processed and sent to a blockchain
node but has not yet been broadcast onchain.
- `CONFIRMED`: the transaction has been broadcast onchain and is awaiting
the required number of confirmations.
- `COMPLETE`: the transaction has reached the required confirmations and
the funds are available in the destination account.
- `CANCELED`: a cancel request for the transaction has been confirmed.
- `FAILED`: the transaction failed (for example, due to insufficient
balance or a failed challenge).
# Update a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/update-subscription
openapi/configurations_2.yaml patch /v2/notifications/subscriptions/{id}
Update subscription endpoint to receive notifications.
# Contracts API error codes
Source: https://developers.circle.com/api-reference/contracts/error-codes
Descriptions of error codes returned by the Contracts API.
For error response shapes and general errors that can be returned by any Circle
API, see [API errors](/api-reference/errors).
## Contract errors
| Error code | HTTP code | Error message | Description |
| - | - | - | - |
| `175001` | `404` | `Contract not found.` | The specified contract does not exist in the system. |
| `175002` | `400` | `No ABI JSON for the target contract.` | Cannot execute a read function on a contract without the ABI JSON. |
| `175003` | `400` | `Constructor parameters length must match constructor signature.` | The number of constructor parameters 프로젝트로 돌아가기
