bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 16쪽
accounts-from-group
openapi/accounts.yaml post /v1/accounts/groups/{groupId}/unassign
Removes up to 100 accounts from the target custody account group.
All-or-nothing: every account listed must currently belong to this
group, otherwise the call fails with 404 and no assignment row is
removed.
# Update an account
Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/update-account
openapi/accounts.yaml put /v1/accounts/{accountId}
Updates mutable fields on an account. Only fields present in the
request body are changed; omitted fields are left untouched.
# Update a custody account group
Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/update-account-group
openapi/accounts.yaml put /v1/accounts/groups/{groupId}
Renames a custody account group. The new name must be unique
(case-insensitive) within the calling entity.
# Update a webhook subscription
Source: https://developers.circle.com/api-reference/digital-asset-accounts/all/update-subscription
openapi/accounts.yaml patch /v2/notifications/subscriptions/{id}
Update a webhook subscription's name or enabled state.
# End User Onboarding API
Source: https://developers.circle.com/api-reference/end-user-onboarding
Create and manage onboarding applications for business customers.
Create Know Your Business (KYB) applications for your customers. Add data,
upload files, and submit for review—all in one REST API.
<Warning>
End User Onboarding API access is enabled per account. Contact your [Circle
representative](mailto:sales@circle.com) to get sandbox and production access
before calling the API.
</Warning>
## Get started
<CardGroup>
<Card title="End User Onboarding documentation" icon="book" href="/end-user-onboarding">
Learn how the onboarding flow works.
</Card>
<Card title="Application states" icon="diagram-project" href="/end-user-onboarding/references/application-states">
See how applications change state.
</Card>
<Card title="Error codes" icon="triangle-exclamation" href="/api-reference/end-user-onboarding/error-codes">
Look up numeric `code` values and the partner action for each.
</Card>
</CardGroup>
## Endpoint categories
<CardGroup>
<Card title="Partner clients" icon="users" href="/api-reference/end-user-onboarding/create-partner-client">
Create and retrieve the businesses you onboard.
</Card>
<Card title="Partner applications" icon="file-lines" href="/api-reference/end-user-onboarding/list-applications">
Track applications from draft to final review.
</Card>
<Card title="Partner documents" icon="file-arrow-up" href="/api-reference/end-user-onboarding/list-documents">
Upload and manage compliance documents.
</Card>
<Card title="Partner RFIs" icon="clipboard-check" href="/api-reference/end-user-onboarding/list-rfis">
Respond to compliance team requests and resubmit data.
</Card>
<Card title="Partner sections" icon="table-list" href="/api-reference/end-user-onboarding/list-sections">
Read and save sections of an application.
</Card>
</CardGroup>
# Save data for multiple sections in a single request
Source: https://developers.circle.com/api-reference/end-user-onboarding/bulk-save
openapi/partner-openapi.yaml patch /v1/onboarding/partner/applications/{applicationId}/data
Accepts a JSON object keyed by section name. Each value is the same payload shape as PUT /sections/{sectionName}. Validation is atomic: all sections are validated before any data is saved, and if any section fails validation the entire request is rejected. Saves are sequential: after validation passes, sections are persisted one at a time. Array sections use upsert semantics: items with refId update existing entities, items without refId create new entities. Existing entities not included are preserved. The response data field is an object keyed by section name containing the saved data for each section.
# Cancel an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/cancel-application
openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}
Cancels a draft ONBOARDING_APPLICATION. Other operation types are not currently cancellable.
# Add a comment to an RFI
Source: https://developers.circle.com/api-reference/end-user-onboarding/create-comment
openapi/partner-openapi.yaml post /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}/comments
# Create a partner client
Source: https://developers.circle.com/api-reference/end-user-onboarding/create-partner-client
openapi/customer-orchestration.yaml post /v1/partner/clients
Creates a new client entity and initializes an onboarding application in a single request. The response contains both the `clientEntityId` and the `applicationId` for the newly created draft application.
Each `clientName` and `country` combination identifies one client. Submitting a combination that already exists returns the existing client's `clientEntityId` and `applicationId` instead of creating a new client. A `409 Conflict` error means two requests created the same client at once; retry the request.
# Delete a comment on an RFI
Source: https://developers.circle.com/api-reference/end-user-onboarding/delete-comment
openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}/comments/{commentId}
# Delete a document
Source: https://developers.circle.com/api-reference/end-user-onboarding/delete-document
openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}/documents/{documentId}
# Download a document
Source: https://developers.circle.com/api-reference/end-user-onboarding/download-document
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/documents/{documentId}
# End User Onboarding API error codes
Source: https://developers.circle.com/api-reference/end-user-onboarding/error-codes
Numeric error codes returned by the End User Onboarding API, with HTTP status, public message, and partner action.
The End User Onboarding API returns an HTTP status and a JSON body with a
numeric `code` and a `message`. The `message` is the generic HTTP phrase for
that status, such as `Not found` or `Gateway timeout`. Use `code` to tell apart
errors that share one HTTP status and one phrase.
For error response shapes and general errors that any Circle API can return, see
[API errors](/api-reference/errors).
## Two not found responses
Both of these responses use HTTP 404 and `message: "Not found"`. The `code`
tells them apart.
**Unknown application (`181103`):**
```json theme={null}
{
"code": 181103,
"message": "Not found"
}
```
**Device check missing (`181110`):**
```json theme={null}
{
"code": 181110,
"message": "Not found"
}
```
## Shared status codes
| HTTP status | Codes | How to tell them apart |
| - | - | - |
| `404` | `181103`, `181110` | `181103` is an unknown application. `181110` means the required device check was not run. |
| `504` | `181109`, `181111` | `181109` is an identity verification (IDV) wait. `181111` is a device-check wait. |
| `409` | `181104`, `181105` | `181104` is the wrong application state. `181105` is idempotency key reuse. |
| `422` | `181100`, `181101` | `181100` is field validation. The body includes `errors[]` with per-field `field`, `code`, `message`, and `section`. `181101` means one or more sections are incomplete. |
## Error codes (181100-181111)
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `181100` | `422` | `Unprocessable entity` | Field validation failed. Read `errors[]`, fix the payload, then retry. |
| `181101` | `422` | `Unprocessable entity` | One or more sections are incomplete. Complete every required section, then retry. |
| `181102` | `400` | `Bad request` | Fix the malformed request body or headers, then retry. |
| `181103` | `404` | `Not found` | Confirm the application ID exists and that your API key can access it. |
| `181104` | `409` | `Conflict` | Fetch the application and retry when its status allows this operation. |
| `181105` | `409` | `Conflict` | Retry with a new `X-Idempotency-Key` after an idempotency conflict. |
| `181106` | `403` | `Forbidden` | Use an API key that includes the required scope. |
| `181107` | `401` | `Unauthorized` | Send a valid Bearer token in the `Authorization` header. |
| `181108` | `500` | `Internal server error` | The device-check lookup failed. The application status is unchanged. Don't treat this as a decline. Retry later. See [Collect device risk signals](/end-user-onboarding/howtos/collect-device-risk-signals). |
| `181109` | `504` | `Gateway timeout` | Identity verification didn't reach a decision in time. Don't treat this as a missing device check. Retry later. |
| `181110` | `404` | `Not found` | The device check wasn't run. The application status is unchanged. Run the device check, then retry submit. See [Collect device risk signals](/end-user-onboarding/howtos/collect-device-risk-signals). |
| `181111` | `504` | `Gateway timeout` | The device check hasn't finished. The application status is unchanged. Retry later. Don't treat this as a missing device check. Don't treat this as an IDV timeout. See [Collect device risk signals](/end-user-onboarding/howtos/collect-device-risk-signals). |
If a Partner API code is not allowlisted, the response uses `code: -1`. Retry
with backoff. Confirm that the expected code is in this catalog.
# Retrieve data for all visible sections
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-all-data
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/data
Returns all visible section data keyed by section name alongside section statuses. The data object is round-trip compatible with PATCH /{applicationId}/data. Sections that do not contribute to application progress are excluded.
# Retrieve an application by ID
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-application
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}
# Get the JSON Schema (draft 2020-12) for an application's template
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-application-schema
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/schema
# List active certifications for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-certifications
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/certifications
Returns the active certifications the end user must agree to for this application, including the HTML content, certification id, and metadata. Pass the returned ids back on POST /{applicationId}/submit as certificationIds to explicitly acknowledge them, or omit certificationIds to let the service auto-resolve the active set.
# Get a partner client
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-partner-client
openapi/customer-orchestration.yaml get /v1/partner/clients/{clientEntityId}
Returns a single client by its `clientEntityId`, scoped to your partner account. Requesting a client that does not exist — or one that belongs to a different partner — returns a `404 Not Found` error.
The response always carries the `clientEntityId` and `created` timestamp. The profile fields (`clientName`, `country`, `clientType`, `businessDetails`) echo the details submitted at creation, while `status` and `balances` are enriched by Circle and omitted when not available.
# Get RFI detail with comment history
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-rfi
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}
# Retrieve section data for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/get-section
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}
Returns field data for the specified section. When typedValues=true, array/object/number field values are emitted as native JSON nodes instead of strings.
# List applications for the authenticated partner
Source: https://developers.circle.com/api-reference/end-user-onboarding/list-applications
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications
# List documents for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/list-documents
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/documents
# List partner clients
Source: https://developers.circle.com/api-reference/end-user-onboarding/list-partner-clients
openapi/customer-orchestration.yaml get /v1/partner/clients
Retrieves the clients created under your partner account, newest first. Results are cursor-paginated, forward-only, via the `Link` response header. Each item always carries the `clientEntityId` and `created` timestamp. The profile fields (`clientName`, `country`, `clientType`, `businessDetails`) echo the details submitted at creation, while `status` and `balances` are enriched by Circle and omitted when not available.
# List RFI bundles for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/list-rfis
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/rfis
# List sections for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/list-sections
openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/sections
Returns visible sections with statuses. When includeData=true, each entry also includes the section's current field data — useful for rendering a progress view alongside prefilled form data. When typedValues=true (only meaningful with includeData=true), array/object/number field values are emitted as native JSON nodes instead of strings.
# Remove an entity from an array section
Source: https://developers.circle.com/api-reference/end-user-onboarding/remove-entity
openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}/{refId}
# Save section data for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/save-section
openapi/partner-openapi.yaml put /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}
Saves field data for a section. The request body is a JSON object whose shape is defined by the section's JSON Schema (retrieve it via GET /{applicationId}/schema). For MULTIPLE array sections, maxItems is enforced and over-limit payloads return 422.
# Submit an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/submit-application
openapi/partner-openapi.yaml post /v1/onboarding/partner/applications/{applicationId}/submit
# Update a comment on an RFI
Source: https://developers.circle.com/api-reference/end-user-onboarding/update-comment
openapi/partner-openapi.yaml put /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}/comments/{commentId}
# Submit field data in response to an UPDATE_FIELD or NEW_FIELD RFI
Source: https://developers.circle.com/api-reference/end-user-onboarding/update-rfidata
openapi/partner-openapi.yaml patch /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}
# Upload a document for an application
Source: https://developers.circle.com/api-reference/end-user-onboarding/upload-document
openapi/partner-openapi.yaml post /v1/onboarding/partner/applications/{applicationId}/documents
# API errors
Source: https://developers.circle.com/api-reference/errors
Common error response formats and codes returned by Circle APIs.
Circle APIs return an
[HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) when
they encounter an error:
* `4xx` errors are client errors. They communicate a mistake in the request and,
where possible, suggest a fix.
* `5xx` errors are unexpected server-side errors.
Product-specific error codes are documented on each product's error codes page.
See [Wallets](/api-reference/wallets/error-codes),
[Contracts](/api-reference/contracts/error-codes),
[Mint](/api-reference/circle-mint/error-codes),
[CPN](/api-reference/cpn/error-codes), and
[End User Onboarding](/api-reference/end-user-onboarding/error-codes).
## General error format
HTTP status codes do not always provide sufficient information to determine the
cause of the error. The response body contains additional Circle-specific error
information. For example, if a request contains an invalid parameter, the
response includes the following:
**Header**
```http theme={null}
HTTP/1.1 400 Bad Request
Content-Type: application/json
```
**Body**
```json theme={null}
{
"code": 2,
"message": "API parameter invalid"
}
```
## Extended error format
For validation failures, the response includes an `errors` array with per-field
detail. For example, if a request is missing a required field:
**Header**
```http theme={null}
HTTP/1.1 400 Bad Request
Content-Type: application/json
```
**Body**
```json theme={null}
{
"code": 2,
"message": "API parameter invalid",
"errors": [
{
"error": "required",
"message": "fail to bind request to CreateWalletSetRequest: EOF",
"location": "field1",
"invalidValue": "null",
"constraints": {}
}
]
}
```
## General errors
The following errors can be returned for any request.
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `-1` | `400` | `Something went wrong` | An unknown error occurred. Retry with exponential backoff. |
| `3` | `403` | `Forbidden` | The API key does not have access to the requested endpoint. |
| `2` | `400` | `API parameter invalid` | The request body or a parameter value is invalid. Read the `message` field for specifics. |
# Get payment status
Source: https://developers.circle.com/api-reference/facilitator-service/get-payment-status
openapi/facilitator-service.yaml get /v1/facilitator/x402/status/{paymentId}
Returns the current status of a payment. Use this endpoint to reconcile
a payment that settlement left unresolved with
`errorReason: settlement_pending`.
Status values are `pending`, `completed`, or `failed`.
# Get supported x402 payment kinds
Source: https://developers.circle.com/api-reference/facilitator-service/get-supported
openapi/facilitator-service.yaml get /v1/facilitator/x402/supported
Returns the x402 payment kinds and extensions Facilitator Service accepts.
# Settle an x402 payment
Source: https://developers.circle.com/api-reference/facilitator-service/settle-payment
openapi/facilitator-service.yaml post /v1/facilitator/x402/settle
Settles an x402 payment. Facilitator Service validates the buyer's EIP-3009
authorization, screens both parties, records the payment, and submits
the USDC transfer through a Circle relayer.
A settlement outcome always uses HTTP 200; there is no pending status
code. A terminal result means settlement resolved within the HTTP wait
window. If the outcome is unresolved at the wait deadline, the 200
response carries `success: false` with
`errorReason: settlement_pending` and a `paymentId`. Pending is not
failure: settlement continues, and
[Get payment status](/api-reference/agent-stack/facilitator-service/get-payment-status)
reconciles the outcome. Do not fulfill on pending.
A rejected request or an internal failure uses the 4xx and 5xx codes
below instead, and carries no settlement outcome.
Include a `payment-identifier` extension in the request body for
idempotency scoped to your seller account. Retries with the same
identifier converge on the same payment. Without an identifier, a
retry must reuse the exact same signed buyer authorization or the
retry is treated as a new charge.
# Verify an x402 payment
Source: https://developers.circle.com/api-reference/facilitator-service/verify-payment
openapi/faci프로젝트로 돌아가기
