bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 17쪽
litator-service.yaml post /v1/facilitator/x402/verify
Validates an x402 payment payload without creating a payment, consuming
keyless trial usage, or submitting anything onchain. Use this endpoint
for verification purposes. To settle a payment, see
[Settle an x402 payment](/api-reference/agent-stack/facilitator-service/settle-payment).
# Gateway API
Source: https://developers.circle.com/api-reference/gateway
Access and manage a unified USDC balance across multiple blockchains with instant transfers in under 500 ms.
Gateway is permissionless and built around non-custodial Gateway Wallet
contracts on each supported blockchain. Deposit once, then call the API from
your app.
## Get started
<CardGroup>
<Card title="Gateway documentation" icon="book" href="/gateway">
Learn how Circle Gateway works.
</Card>
<Card title="Supported blockchains" icon="link" href="/gateway/references/supported-blockchains">
See which blockchains Gateway supports.
</Card>
<Card title="Webhooks" icon="bell" href="/api-reference/gateway/all/get-permissionless-subscriptions">
Set up permissionless webhook subscriptions.
</Card>
</CardGroup>
## Endpoint categories
<CardGroup>
<Card title="Gateway" icon="dungeon" href="/api-reference/gateway/all/get-token-balances">
Read balances, request attestations, and inspect transfers.
</Card>
<Card title="Gateway Batch" icon="layer-group" href="/api-reference/gateway/all/submit-batch-authorization">
Submit batched transfer authorizations.
</Card>
</CardGroup>
## OpenAPI specifications
The Gateway API reference is generated from this OpenAPI specification:
* `https://developers.circle.com/openapi/gateway.yaml`
See [OpenAPI Specifications](/api-reference/openapi-specifications) for the full
catalog of Circle's API specs.
# Get supported x402 payment kinds
Source: https://developers.circle.com/api-reference/gateway-nanopayments/get-supported-x402payment-kinds
openapi/gateway-nanopayments.yaml get /v1/x402/supported
Returns the payment kinds supported by Circle Gateway for x402 batching.
Each kind includes the GatewayWallet contract address in
`extra.verifyingContract` which clients use for EIP-712 signing, and an
`extra.assets` array containing the supported tokens with their addresses,
symbols, and decimals.
# Get an x402 transfer by ID
Source: https://developers.circle.com/api-reference/gateway-nanopayments/get-x402transfer-by-id
openapi/gateway-nanopayments.yaml get /v1/x402/transfers/{id}
Retrieves a single x402 transfer by its unique identifier.
# Search x402 transfers
Source: https://developers.circle.com/api-reference/gateway-nanopayments/search-x402transfers
openapi/gateway-nanopayments.yaml get /v1/x402/transfers
Returns a paginated list of x402 transfers matching the given filters.
Supports cursor-based pagination via pageAfter / pageBefore.
Filtering by `status` requires at least one of `from`, `to`, or `nonce`
in the same request. If you supply `status` on its own, or alongside
only `network`, `token`, or a date range, the request returns `400`.
Searching every transfer in a given status isn't supported.
# Settle an x402 payment
Source: https://developers.circle.com/api-reference/gateway-nanopayments/settle-x402payment
openapi/gateway-nanopayments.yaml post /v1/x402/settle
Settles an x402 payment by submitting the EIP-3009 authorization.
The authorization will be verified, the sender's balance locked, and
the transaction queued for batch processing.
# Verify an x402 payment payload
Source: https://developers.circle.com/api-reference/gateway-nanopayments/verify-x402payment
openapi/gateway-nanopayments.yaml post /v1/x402/verify
Verifies that an x402 payment payload can be processed by running
all read-only validation checks (scheme, network, token, signature,
temporal constraints, address/amount matching). A valid result does
not guarantee settlement — balance and nonce checks only happen at
settle time.
# Create a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/create-permissionless-subscription
openapi/gateway.yaml post /v2/notifications/subscriptions/permissionless
Create a permissionless webhook subscription by configuring an endpoint to receive event notifications. Specify the environment, wallet addresses to monitor, blockchain domains to watch, and event types to receive.
# Create a transfer attestation for transferring tokens
Source: https://developers.circle.com/api-reference/gateway/all/create-transfer-attestation
openapi/gateway.yaml post /v1/transfer
Generates a transfer attestation and operator signature for transferring tokens between domains
# Delete a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/delete-permissionless-subscription
openapi/gateway.yaml delete /v2/notifications/subscriptions/permissionless/{id}
Delete an existing permissionless webhook subscription.
# Estimate fees and expiration block heights for a transfer
Source: https://developers.circle.com/api-reference/gateway/all/estimate-transfer
openapi/gateway.yaml post /v1/estimate
Calculates the required fees and expiration block heights for a transfer without requiring signatures or executing the transaction.
# Get pending deposits for specified addresses
Source: https://developers.circle.com/api-reference/gateway/all/get-deposits
openapi/gateway.yaml post /v1/deposits
Returns pending deposits for each specified depositor address across different domains where that address is valid.
# Get Gateway info for supported domains and tokens
Source: https://developers.circle.com/api-reference/gateway/all/get-gateway-info
openapi/gateway.yaml get /v1/info
Provides information about the API and details of the supported domains and tokens.
# Get a notification signature public key
Source: https://developers.circle.com/api-reference/gateway/all/get-permissionless-notification-signature
openapi/gateway.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 webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/get-permissionless-subscription
openapi/gateway.yaml get /v2/notifications/subscriptions/permissionless/{id}
Retrieve an existing permissionless webhook subscription.
# Get all webhook subscriptions
Source: https://developers.circle.com/api-reference/gateway/all/get-permissionless-subscriptions
openapi/gateway.yaml get /v2/notifications/subscriptions/permissionless
Retrieve an array of existing permissionless webhook subscriptions.
# Get token balances for specified addresses
Source: https://developers.circle.com/api-reference/gateway/all/get-token-balances
openapi/gateway.yaml post /v1/balances
Returns the current available balance of each specified address across different domains where that address is valid
# Get a transfer by ID
Source: https://developers.circle.com/api-reference/gateway/all/get-transfer-by-id
openapi/gateway.yaml get /v1/transfer/{id}
Returns detailed information about a transfer.
# Get full TransferSpec by transferSpecHash
Source: https://developers.circle.com/api-reference/gateway/all/get-transfer-spec
openapi/gateway.yaml get /v1/transferSpec/{transferSpecHash}
Retrieve the full TransferSpec for a given transferSpecHash.
# Send a test notification
Source: https://developers.circle.com/api-reference/gateway/all/send-permissionless-subscription-test-notification
openapi/gateway.yaml post /v2/notifications/subscriptions/permissionless/{id}/test
Send a test notification to the subscriber endpoint. The notification has notificationType "webhooks.test".
# Submit an EIP-3009 authorization to be batched
Source: https://developers.circle.com/api-reference/gateway/all/submit-batch-authorization
openapi/gateway.yaml post /v1/batch/submit
Submit a single-chain transfer authorization using EIP-3009 signature.
The authorization will be verified, the sender's balance locked, and
the transaction queued for batch processing.
# Test subscription connection
Source: https://developers.circle.com/api-reference/gateway/all/test-permissionless-subscription-connection
openapi/gateway.yaml post /v2/notifications/subscriptions/permissionless/{id}/testConnection
Verify that the subscriber endpoint for the given subscription is reachable.
# Update a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/update-permissionless-subscription
openapi/gateway.yaml patch /v2/notifications/subscriptions/permissionless/{id}
Update a webhook subscription. Metadata fields can be updated independently. To update filters, provide `notificationTypes`, `addresses`, and `domains` together; those fields fully replace the existing filters.
# Idempotent requests
Source: https://developers.circle.com/api-reference/idempotent-requests
Idempotency keys let you safely retry Circle API calls.
Circle APIs support
[idempotent requests](https://en.wikipedia.org/wiki/Idempotence), so making the
same request multiple times produces the same result. This lets you safely retry
API calls if something goes wrong.
## Idempotency keys
Certain endpoints require you to generate an idempotency key to identify the
request. For endpoints that require an idempotency key, each request must have a
unique key.
The server uses this key to identify a specific request. When a request is made
with the same idempotency key, the server returns the original response instead
of executing the operation again.
For endpoints that require it, the idempotency key must be in
[UUID version 4](https://en.wikipedia.org/wiki/Universally_unique_identifier)
format.
The following example demonstrates how to generate an idempotency key in
Node.js:
```typescript theme={null}
import crypto from "crypto";
function generateIdempotencyKey(): string {
return crypto.randomUUID();
}
const idempotencyKey: string = generateIdempotencyKey();
console.log(idempotencyKey); // e.g. "f47ac10b-58cc-4372-a567-0e02b2c3d479"
```
# API keys
Source: https://developers.circle.com/api-reference/keys
Learn about the different types of API keys used to authenticate requests to Circle's platform.
Certain products use API keys to authenticate requests. Circle provides two
types of keys for different use cases: [API keys](#api-keys) for server-side
access and [client keys](#client-keys) for frontend applications.
<Note>
Permissionless products like CCTP and Gateway do not require an API key.
</Note>
<CardGroup>
<Card title="API key" icon="server">
Authenticate server-side requests to Circle's RESTful APIs.
</Card>
<Card title="Client key" icon="browser">
Authenticate client applications with domain or app binding. Required for
frontend SDKs.
</Card>
</CardGroup>
## API keys
An API key is a unique string used to authenticate and enable access to
privileged operations on Circle's APIs. It's required for any RESTful API
requests to Circle services. Without it, requests will fail.
### Keep your API keys safe
API keys allow access to sensitive operations, so you must secure them.
* **Avoid public exposure**: Never share API keys or include them in client-side
code, public repositories, or other public mediums.
* **Manage securely**: Use the Circle Console to generate and manage API keys.
When generating a key, copy it exactly as displayed.
<Warning>Losing control of your API key can result in financial loss.</Warning>
### API key authentication
Each key is tied to one environment. Use `TEST_API_KEY` for testnet requests and
`LIVE_API_KEY` for mainnet requests.
<CodeGroup>
```text Testnet theme={null}
authorization: Bearer TEST_API_KEY:YOUR_KEY_ID:YOUR_SECRET
```
```text Mainnet theme={null}
authorization: Bearer LIVE_API_KEY:YOUR_KEY_ID:YOUR_SECRET
```
</CodeGroup>
Always use the full key string, including the prefix and all segments. Don't
split the key into parts. If you store keys in a `.env` file, set
`CIRCLE_API_KEY` to the key for the environment you're currently targeting.
### Test authentication
To verify your API key setup, use the following `curl` command to retrieve
wallets:
```bash theme={null}
curl --request GET \
--url https://api.circle.com/v1/w3s/wallets \
--header 'accept: application/json' \
--header 'authorization: Bearer <API_KEY>'
```
A successful response looks like this:
```json theme={null}
{
"data": {
"wallets": []
}
}
```
An error response looks like this:
```json theme={null}
{
"code": 401,
"message": "Malformed authorization. Are the credentials properly encoded?"
}
```
### API keys in Arc App Kits
Three App Kit capabilities use Circle API keys:
| Capability | API key | Without a key |
| - | - | - |
| [Onramp](https://docs.arc.io/app-kit/onramp) | Required | Integration won't work |
| [Swap](https://docs.arc.io/app-kit/swap) | Optional | Shares a public rate limit |
| [Earn](https://docs.arc.io/app-kit/earn) | Optional | Shares a public rate limit |
For Swap and Earn, an API key gives you a higher rate limit instead of sharing
one quota with all other unauthenticated traffic. Use a key in production or any
time you expect to hit the shared limit. Mainnet access for Swap and Earn
doesn't require completing full onboarding or identity verification.
<Note>
Moving from a Swap kit key to an API key? API keys are specific to one
environment. Create one API key for testnet and another for mainnet, and switch
the credential when you move from development to production.
</Note>
***
## Client keys
A client key is a unique string used to authenticate and authorize API access
for apps using Circle's SDKs. A client key is linked to either a specific host
domain (websites), bundle ID (iOS), or package name (Android). This restricts
access to pre-configured apps.
<Note>
A client key must be included in the headers of all modular wallets SDK API
calls.
</Note>
### Best practices for client keys
Client keys enable access to sensitive application operations, so protecting
them is critical. Follow these best practices:
1. **Use separate keys for each application**: Create separate keys for web and
mobile apps (iOS, Android) to prevent shared vulnerabilities.
2. **Monitor for misuse**: Set up alerts for unusual activity, such as
unexpected spikes in API calls, and use monitoring tools to detect anomalies.
3. **Rotate keys regularly**: Regenerate client keys periodically and update
them in your apps to reduce risk if a key is compromised.
4. **Store keys securely**: Use secure storage options like Local Storage or
Secure Storage for mobile apps, and avoid unnecessary exposure.
5. **Restrict access**: Limit the scope of client keys by associating them with
specific apps or domains to minimize potential misuse.
***
## Kit keys (legacy)
<Note>
**Kit keys are legacy.** You can no longer create kit keys. Use an
[API key](#api-keys) for new [Swap](https://docs.arc.io/app-kit/swap)
integrations in Arc App Kits. Existing kit keys remain visible in the
[Circle Console](https://console.circle.com/legacy-keys) and continue to work,
so no action is required. There's no end-of-life date.
</Note>
A kit key is a unique string used to authenticate access for Circle's developer
kits. Kit keys provide a single credential that works across both testnet and
mainnet environments, reducing configuration overhead when building.
### Keep your kit keys safe
Kit keys enable access to SDK features, so protecting them is essential.
* **Avoid public exposure**: Never share kit keys or include them in client-side
code, public repositories, or other public mediums.
* **Manage securely**: Use the
[Circle Console](https://console.circle.com/legacy-keys) to view and manage
your kit keys.
<Warning>
Losing control of your kit key can result in unauthorized access to SDK
capabilities.
</Warning>
# OpenAPI Specifications
Source: https://developers.circle.com/api-reference/openapi-specifications
Find the machine-readable OpenAPI specification for every Circle API, with direct links to each published spec file.
Use these machine-readable OpenAPI specifications to generate client code, drive
API tooling, or give an AI agent accurate request and response shapes. Every API
in this reference has one.
Every spec is hosted at `https://developers.circle.com/openapi/` and served as a
raw YAML file. Add the filename to that base path to fetch a spec directly:
```bash theme={null}
curl https://developers.circle.com/openapi/cctp.yaml
```
## Available specifications
Specs are grouped by the product they power. A few specs power more than one
product, so they appear under each. Where the same filename appears under
multiple products, it's the same file—not a product-specific variant.
| Product | Specification |
| :- | :- |
| Wallets | [`configurations_1.yaml`](https://developers.circle.com/openapi/configurations_1.yaml) |
| | [`configurations_2.yaml`](https://developers.circle.com/openapi/configurations_2.yaml) |
| | [`developer-controlled-wallets.yaml`](https://developers.circle.com/openapi/developer-controlled-wallets.yaml) |
| | [`user-controlled-wallets.yaml`](https://developers.circle.com/openapi/user-controlled-wallets.yaml) |
| | [`buidl-wallets.yaml`](https://developers.circle.com/openapi/buidl-wallets.yaml) |
| | [`compliance.yaml`](https://developers.circle.com/openapi/compliance.yaml) |
| Contracts | [`configurations_2.yaml`](https://developers.circle.com/openapi/configurations_2.yaml) |
| | [`smart-contract-platform.yaml`](https://developers.circle.com/openapi/smart-contract-platform.yaml) |
| CCTP | [`cctp.yaml`](https://developers.circle.com/openapi/cctp.yaml) |
| Gateway | [`gateway.yaml`](https://developers.circle.com/openapi/gateway.yaml) |
| Circle Mint | [`account.yaml`](https://developers.circle.com/openapi/account.yaml) |
| | [`general.yaml`](https://developers.circle.com/openapi/general.yaml) |
| | [`institutional.yaml`](https://developers.circle.com/openapi/institutional.yaml) |
| | [`payments.yaml`](https://developers.circle.com/openapi/payments.yaml) |
| | [`payouts.yaml`](https://developers.circle.com/openapi/payouts.yaml) |
| | [`cross-currency.yaml`](https://developers.circle.com/openapi/cross-currency.yaml) |
| | [`reserve-management.yaml`](https://developers.circle.com/openapi/reserve-management.yaml) |
| | [`credit.yaml`](https://developers.circle.com/openapi/credit.yaml) |
| | [`partner-openapi.yaml`](https://developers.circle.com/openapi/partner-openapi.yaml) |
| Circle Payments Network | [`configurations.yaml`](https://developers.circle.com/openapi/configurations.yaml) |
| | [`cpn-ofi.yaml`](https://developers.circle.com/openapi/cpn-ofi.yaml) |
| | [`accounts.yaml`](https://developers.circle.com/openapi/accounts.yaml) |
| | [`payments.yaml`](https://developers.circle.com/openapi/payments.yaml) |
| | [`payouts.yaml`](https://developers.circle.com/openapi/payouts.yaml) |
| | [`managed-payments.yaml`](https://developers.circle.com/openapi/managed-payments.yaml) |
| Match | [`match.yaml`](https://developers.circle.com/openapi/match.yaml) |
| StableFX | [`stablefx.yaml`](https://developers.circle.com/openapi/stablefx.yaml) |
| xReserve | [`xreserve.yaml`](https://developers.circle.com/openapi/xreserve.yaml) |
| Digital Asset Accounts | [`accounts.yaml`](https://developers.circle.com/openapi/accounts.yaml) |
| End User Onboarding | [`customer-orchestration.yaml`](https://developers.circle.com/openapi/customer-orchestration.yaml) |
| | [`partner-openapi.yaml`](https://developers.circle.com/openapi/partner-openapi.yaml) |
<Note>
Each rendered API reference page also exposes its own source spec: append
`.md` to any endpo프로젝트로 돌아가기
