bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 23쪽
check the list of Ethereum Dapps that support SCA: https://eip1271.io/.
To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body.
# Create a challenge to update PIN
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/update-user-pin-challenge
openapi/user-controlled-wallets.yaml put /v1/w3s/user/pin
Creates a challenge to update a user's PIN using the current PIN.
# Update a wallet
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/update-wallet
openapi/user-controlled-wallets.yaml put /v1/w3s/wallets/{id}
Updates info for a single user-controlled wallet using it's unique identifier.
# How-to: Set up a webhook endpoint
Source: https://developers.circle.com/api-reference/webhook-endpoints
Expose a subscriber endpoint and subscribe to webhook notifications from a Circle product.
To start receiving webhook notifications from a Circle product, expose a
subscriber endpoint, then register that endpoint as a subscriber to the events
you care about. The exact flow depends on which
[notification API version](/api-reference/webhooks#notification-api-versions)
the product uses.
<Tabs>
<Tab title="v2 notifications">
Used by [Circle Wallets](/wallets), [Circle Contracts](/contracts),
[CPN payments](/cpn), [CPN Managed Payments](/cpn/managed-payments),
[Digital Asset Accounts](/digital-asset-accounts), [Gateway](/gateway), and
[StableFX](/stablefx).
<Steps>
<Step title="Set up a subscriber endpoint">
Expose a publicly accessible HTTPS endpoint that:
* Is reachable from the public internet.
* Handles both `HEAD` and `POST` requests. Circle uses `HEAD` to validate the
URL when you create or update a subscription, and `POST` to deliver
notifications.
* Responds to `POST` requests with a `2XX` status code so Circle treats the
delivery as successful. Any other status causes Circle to retry the
notification.
To test before deploying a real endpoint, generate a temporary URL with
[webhook.site](https://webhook.site/) and use it as your subscriber endpoint.
</Step>
<Step title="Allowlist Circle's source IP addresses">
Configure your firewall, load balancer, or cloud security groups so your
endpoint only trusts webhook requests from Circle's source IP addresses. This
blocks unauthenticated traffic at the network edge as a layer of defense in
addition to [signature verification](/api-reference/verify-webhook-signatures).
Allowlist the IP addresses for each product you integrate with separately.
**Wallets, Contracts, Gateway, and Digital Asset Accounts** share the same
webhook delivery infrastructure:
* `54.243.112.156`
* `100.24.191.35`
* `54.165.52.248`
* `54.87.106.46`
**Circle Payments Network (CPN)**: the same IP set applies to both mainnet and
testnet:
* `35.169.154.32`
* `3.90.127.28`
* `3.230.111.7`
* `54.88.227.75`
**Stablecoin FX (StableFX):**
* `3.230.111.7`
* `3.90.127.28`
* `35.169.154.32`
* `54.88.227.75`
</Step>
<Step title="Subscribe to notifications">
Register your endpoint as a subscriber by calling the Create Subscription
endpoint for your product. Select your product for the request shape:
<Tabs>
<Tab title="Wallets and Contracts">
These products share the same subscription endpoint. See the Create Subscription
reference for [Wallets](/api-reference/wallets/common/create-subscription) or
[Contracts](/api-reference/contracts/common/create-subscription) for the full
schema.
```bash theme={null}
curl --request POST \
--url https://api.circle.com/v2/notifications/subscriptions \
--header "Authorization: Bearer $CIRCLE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"endpoint": "https://your-app.example.com/webhooks",
"notificationTypes": ["*"]
}'
```
Example response:
```json theme={null}
{
"data": {
"id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
"name": "Transactions Webhook",
"endpoint": "https://your-app.example.com/webhooks",
"enabled": true,
"createDate": "2026-01-15T21:47:35.107250Z",
"updateDate": "2026-01-15T21:47:35.107250Z",
"notificationTypes": ["*"],
"restricted": false
}
}
```
</Tab>
<Tab title="Digital Asset Accounts">
Digital Asset Accounts distributors can register a subscription from Circle Hub
or with the API.
## Create a subscription from Circle Hub
Circle Hub takes no code, validates your endpoint on creation, surfaces delivery
status, and lets you pause a subscription without a deploy.
Before you begin, ensure that you've:
* Completed Digital Asset Accounts onboarding, which grants sandbox access
automatically and exposes the **Digital Asset Accounts** capability in
production once the account clears onboarding. See
[Going to production](/digital-asset-accounts/references/going-to-production).
* Deployed a publicly accessible HTTPS endpoint that handles `HEAD` and `POST`
requests and responds to `POST` with a `200 OK`.
Sign in to [Circle Hub](https://hub.circle.com), go to **Developers >
Webhooks**, and select **Create webhook**.
<Steps>
<Step title="Select the capability">
Under **Capability**, select **Digital Asset Accounts**. The event list under
**Events** narrows to the notification types this capability delivers.
</Step>
<Step title="Enter your endpoint">
Enter your endpoint's host and path in **URL**. Circle Hub prefixes the value
with `https://`, so enter `your-app.example.com/webhooks` rather than the full
URL. Optionally add a **Name** to identify the subscription in the table.
</Step>
<Step title="Select the events to receive">
Under **Events**, select the events you want to receive, or select all. See
[Webhook notifications](/api-reference/digital-asset-accounts) for the full
event catalog.
</Step>
<Step title="Create the subscription">
Select **Create webhook**. Circle Hub creates the subscription in the
**Inactive** state and no events are delivered yet. To go active, open the
subscription and select **Test & Activate**. Circle Hub sends a test payload to
your endpoint and activates the subscription once your endpoint responds with
`2XX`. If the test fails, Circle Hub reports the reason, such as a refused
connection, a TLS error, or a response timeout.
</Step>
</Steps>
## Create a subscription with the API
Use the API when you need to manage subscriptions programmatically. Digital
Asset Accounts uses the shared `/v2/notifications/subscriptions` endpoint. See
the
[Create Subscription](/api-reference/digital-asset-accounts/all/create-subscription)
reference for the full schema.
```bash theme={null}
curl --request POST \
--url https://api.circle.com/v2/notifications/subscriptions \
--header "Authorization: Bearer $CIRCLE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"endpoint": "https://your-app.example.com/webhooks",
"notificationTypes": ["*"]
}'
```
Example response:
```json theme={null}
{
"data": {
"id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
"name": "Digital Asset Accounts Webhook",
"endpoint": "https://your-app.example.com/webhooks",
"enabled": true,
"createDate": "2026-01-15T21:47:35.107250Z",
"updateDate": "2026-01-15T21:47:35.107250Z",
"notificationTypes": ["*"],
"restricted": false
}
}
```
</Tab>
<Tab title="CPN">
CPN requires `name` and `enabled` in the request body in addition to the common
fields. See the
[Create Subscription](/api-reference/cpn/common/create-subscription) reference
for the full schema.
```bash theme={null}
curl --request POST \
--url https://api.circle.com/v2/cpn/notifications/subscriptions \
--header "Authorization: Bearer $CIRCLE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"endpoint": "https://your-app.example.com/webhooks",
"name": "CPN Webhooks",
"enabled": true,
"notificationTypes": ["*"]
}'
```
Example response:
```json theme={null}
{
"data": {
"id": "1609aa1c-510a-448d-b9b9-3a13566ff922",
"name": "CPN Webhooks",
"endpoint": "https://your-app.example.com/webhooks",
"enabled": true,
"createDate": "2026-01-15T21:47:35.107250Z",
"updateDate": "2026-01-15T21:47:35.107250Z",
"notificationTypes": ["*"],
"restricted": false
}
}
```
</Tab>
<Tab title="StableFX">
See the [Create Subscription](/api-reference/stablefx/all/create-subscription)
reference for the full schema.
```bash theme={null}
curl --request POST \
--url https://api.circle.com/v2/stablefx/notifications/subscriptions \
--header "Authorization: Bearer $CIRCLE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"endpoint": "https://your-app.example.com/webhooks",
"notificationTypes": ["*"]
}'
```
Example response:
```json theme={null}
{
"data": {
"id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
"name": "Transactions Webhook",
"endpoint": "https://your-app.example.com/webhooks",
"enabled": true,
"createDate": "2026-01-15T21:47:35.107250Z",
"updateDate": "2026-01-15T21:47:35.107250Z",
"notificationTypes": ["*"],
"restricted": false
}
}
```
</Tab>
<Tab title="Gateway">
Gateway uses a subscription that includes the wallet addresses and blockchain
domains to monitor. See the
[Create Subscription](/api-reference/gateway/all/create-permissionless-subscription)
reference for the full schema.
```bash theme={null}
curl --request POST \
--url https://api.circle.com/v2/notifications/subscriptions/permissionless \
--header "Authorization: Bearer $CIRCLE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"environment": "mainnet",
"endpoint": "https://your-app.example.com/webhooks",
"addresses": ["0xYourWalletAddress"],
"domains": [0],
"notificationTypes": ["gateway.*"]
}'
```
Example response:
```json theme={null}
{
"data": {
"id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
"name": "Gateway Webhooks",
"endpoint": "https://your-app.example.com/webhooks",
"environment": "mainnet",
"enabled": true,
"addresses": ["0xYourWalletAddress"],
"domains": [0],
"notificationTypes": ["gateway.*"],
"createDate": "2026-01-15T21:47:35.107250Z",
"updateDate": "2026-01-15T21:47:35.107250Z"
}
}
```
</Tab>
</Tabs>
</Step>
</Steps>
</Tab>
<Tab title="v1 notifications">
<Warning>
Webhooks v1 are legacy and being phased out. If you have existing integrations
with v1 endpoints, [learn how to migrate to
v2](https://help.circle.com/support/en/migrating-from-v1-webhooks-to-v2-webhooks?id=support_article_view\&sys_kb_id=9e9fe9a63b27c310cfb54b9aa4e45a1f).
</Warning>
Used by [Circle Mint](/circle-mint) and
[End User Onboarding](/end-user-onboarding).
<Steps>
<Step title="Set up a subscriber endpoint">
Expose a publicly accessible HTTPS endpoint that:
* Is reachable from the public internet.
* Handles both `HEAD` and `POST` requests. Circle issues `HEAD` requests as a
connectivity warmup. SNS deliveries arrive as `POST` requests with the SNS
message in the request body.
* Responds with a `2xx` status code so SNS treats the delivery as successful.
To test before deploying a real endpoint, generate a temporary URL with
[webhook.site](https://webhook.site/), use it as your subscriber endpoint, and
copy the `SubscribeURL` from each confirmation message into your browser to
complete the handshake. Expect two confirmation messages, one per region.
</Step>
<Step title="Register your subscription">
Call `POST /v1/notifications/subscriptions` with your endpoint URL.
```bash theme={null}
curl --request POST \
--url https://api.circle.com/v1/notifications/subscriptions \
--header "Authorization: Bearer $CIRCLE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"endpoint": "https://your-app.example.com/webhooks"
}'
```
Example response:
```json theme={null}
{
"data": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"endpoint": "https://your-app.example.com/webhooks",
"subscriptionDetails": [
{
"url": "arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic",
"arn": "arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic:9b1e0c7a-2d84-4f1b-8c3a-71a2650f5c22",
"status": "pending"
},
{
"url": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
"arn": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic:fcb4a2c9-9c4f-4706-b312-6b22650f5d17",
"status": "pending"
}
]
}
}
```
Circle publishes v1 notifications from two AWS regions (`us-east-1` and
`us-west-2`) for redundancy, so `subscriptionDetails[]` contains one entry per
region. Each entry starts as `pending` and moves to `confirmed` independently
once you confirm its own `SubscribeURL` in the next step. v1 subscriptions
deliver all account events; filtering by `notificationTypes` isn't supported.
<Tip>
Circle Mint customers can also register subscriptions through the [Circle Mint
console](https://app.circle.com/) under **Developer → Subscriptions**.
</Tip>
</Step>
<Step title="Confirm the subscription">
After you register the subscription, SNS sends a `POST` to your endpoint with
`Type: SubscriptionConfirmation`. Because Circle publishes from two regions,
your endpoint receives one confirmation message per region (`us-east-1` and
`us-west-2`), each carrying its own `SubscribeURL`. Confirm **both**: open each
`SubscribeURL` in your browser, or have your endpoint fetch it server-side, to
finish the handshake.
The endpoint isn't fully subscribed until both regional `SubscribeURL` values
are confirmed. Each `subscriptionDetails[]` entry moves to `confirmed` as its
own `SubscribeURL` is confirmed; confirm both to ensure uninterrupted event
delivery.
Example `SubscriptionConfirmation` payload (the `us-west-2` message; the
`us-east-1` message has the same shape, with `us-east-1` in its `TopicArn` and
`SubscribeURL`):
```json theme={null}
{
"Type": "SubscriptionConfirmation",
"MessageId": "ddbdcdcf-d36a-45b5-927c-da25b9b009ae",
"Token": "2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
"TopicArn": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
"Message": "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
"SubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=...",
"Timestamp": "2026-04-11T20:50:16.324Z",
"SignatureVersion": "1",
"Signature": "...",
"SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-...pem"
}
```
</Step>
<Step title="(Optional) Manage subscriptions">
List active subscriptions with `GET /v1/notifications/subscriptions` and remove
one with `DELETE /v1/notifications/subscriptions/{id}`. A subscription can be
deleted only when every entry in `subscriptionDetails[]` is `confirmed`,
`deleted`, or a mix of the two. A subscription with any `pending` entry cannot
be deleted. Resolve the pending state first.
| Environment | Active subscription cap | `pending` auto-removal |
| - | - | - |
| Sandbox | 3 | After 30 days |
| Production | 1 | After 72 hours |
</Step>
</Steps>
<Note>
v1 traffic originates from Amazon SNS rather than Circle, so the IP range is
the published [AWS SNS IP
range](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) and
not practical to allowlist narrowly. Rely on [signature
verification](/api-reference/verify-webhook-signatures) to confirm
authenticity.
</Note>
</Tab>
</Tabs>
# Webhooks
Source: https://developers.circle.com/api-reference/webhooks
Learn how Circle uses webhooks to notify your application when events occur, including the event model, delivery behavior, ordering, and idempotency.
Circle uses webhooks to notify your application when events occur. Circle
products handle many operations in the background. When a resource changes
state, Circle sends an HTTP `POST` to the endpoint you configure so your
application can react.
## Notification API versions
Circle offers two notification systems. Which one you integrate with depends on
the product you're using.
| Version | Delivery | Products |
| - | - | - |
| **v2** | Direct HTTPS POST from Circle | Circle Wallets, Circle Contracts, CPN payments, CPN Managed Payments, Digital Asset Accounts, Gateway, StableFX |
| **v1** | Amazon SNS publishes to your endpoint | Circle Mint, End User Onboarding |
The two versions differ in subscription setup, message format, and signature
verification. See [Set up a webhook endpoint](/api-reference/webhook-endpoints)
for the flow that matches your product.
## Event model
Each webhook notification is an HTTP `POST` request to a subscriber endpoint you
configure. The envelope shape depends on the notification API version.
<Tabs>
<Tab title="v2 notifications">
Used by Circle Wallets, Circle Contracts, CPN payments, CPN Managed
Payments, Digital Asset Accounts, Gateway, and StableFX. Each notification
includes:
| Field | Type | Description |
| - | - | - |
| `subscriptionId` | string (UUIDv4) | Identifies the subscription that produced the notification. Use it to route events to the correct handler. |
| `notificationId` | string (UUIDv4) | Uniquely identifies the notification. The same ID is reused if Circle retries delivery, so use it to deduplicate. |
| `notificationType` | string | The event type (for example, `transactions.inbound`, `cpn.payment.completed`). |
| `notification` | object | The resource that changed, including its current state. The shape matches the corresponding API endpoint's response object. |
| `timestamp` | string | ISO 8601 timestamp of the event. |
| `version` | number | Schema version. Always `2`. |
You subscribe to the events your application cares about. When a
corresponding state change occurs in Circle's systems, Circle sends a
notification to your endpoint.
</Tab>
<Tab title="v1 notifications">
<Warning>
Webhooks v1 are legacy and being phased out. If you have existing
integrations with v1 endpoints, [learn how to migrate to
v2](https://help.circle.com/support/en/migrating-from-v1-webhooks-to-v2-webhooks?id=support_article_view\&sys_kb_id=9e9fe9a63b27c310cfb54b9aa4e45a1f).
</Warning>
Used by Circle Mint and End User Onboarding. v1 uses Amazon Simple
Notification Service (SNS) as the delivery layer, so each notification
arrives as an SNS message wrapping the Circle event payload.
The outer SNS envelope includes:
| Field | Type | Description |
| - | - | - |
| `Type` | string | The SNS message type. `Notification` for events, `SubscriptionConfirmation` for the one-time handshake described below. |
| `MessageId` | string | Unique identifier for this delivery. Reused if SNS retries, so use it to deduplicate. |
| `TopicArn` | string | The SNS topic the subscription is bound to. |
| `Message` | string | The Circle event payload, encoded as a JSON string. Parse it to access the inner envelope described next. |
| `Signature` | string | Base64-encoded signature of the canonical message string. |
| `SigningCertURL` | string | URL of the public certificate used to verify `Signature`. See [Verify webhook signatures](/api-reference/verify-webhook-signatures). |
The inner Circle envelope, parsed from `Message`, includes:
| Field | Type | Description |
| - | - | - |
| `clientId` | string (UUIDv4) | Identifies the Circle account that owns the resource. |
| `notificationType` | string | The event topic (for example, `deposits`, `transfers`). The topic determines which resource key is present on the envelope. |
| `version` | number | Schema version for the notification payload. |
| `customAttributes` | object | Echoes selected envelope a프로젝트로 돌아가기
