Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

API Reference

Download OpenAPI Spec

Authentication

The API accepts two types of Bearer tokens:

  • JWT — Obtain one instantly by completing the Sign-In with Ethereum (SIWE) flow below (GET /nonce → POST /verify). JWTs are short-lived session tokens.
  • API Key — Long-lived platform keys for server-to-server integrations. Contact us at support@clkd.xyz to request one.

Pass either token in the Authorization header — the server auto-detects the format.

Important: The address used for authentication must be the address derived from your private spending key (privateKeyToAccount(p_spend)), NOT your connected wallet address. The server identity is this derived auth address — your wallet address never touches the server.

Endpoints marked with 🔒 require a valid Bearer token.

Get HPKE public key

GET/v1/.well-known/hpke-public-key

Retrieve the server's HPKE public key. Clients must encrypt stealth key material with this key before submitting it during account creation or signer enrollment.

Responses
200Default Response
Schema
publicKeyrequiredstring
e.g. "0x..."
publicKeyBase64requiredstring
e.g. "..."
formatrequiredstring
e.g. "hex"
kemrequiredstring
e.g. "X25519-HKDF-SHA256"
aeadrequiredstring
e.g. "AES-128-GCM"
json
{
  "publicKey": "0x...",
  "publicKeyBase64": "...",
  "format": "hex",
  "kem": "X25519-HKDF-SHA256",
  "aead": "AES-128-GCM"
}
Try it
curl -X GET \
  "https://api-stg.clkd.xyz/v1/.well-known/hpke-public-key"

Get nonce

GET/v1/nonce

Generate a one-time nonce tied to the given address. This is the first step of Sign-In with Ethereum (SIWE) — the nonce must be included in the SIWE message passed to verifySignin. Nonces expire after 5 minutes.

Parameters
NameInTypeDescription
address*querystringThe auth address to tie the nonce to. This must be the address derived from your private spending key (i.e. `privateKeyToAccount(p_spend).address`), not your connected wallet address.
Responses
200Random nonce string
Schema
string — Random nonce string
json
"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 20 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 20 requests per 1 minute."
}
Try it
Query Parameters
address
curl -X GET \
  "https://api-stg.clkd.xyz/v1/nonce"

Verify sign-in

POST/v1/verify

Complete Sign-In with Ethereum by submitting the signed SIWE message. Returns a JWT session token and the associated accountId if the address already has an account, or null if the user still needs to register.

Request Body
messagerequiredstring
SIWE message string
signaturerequiredstring
Signature from wallet
authTypestring
Optional lowercase snake_case auth mechanism label, e.g. passkey_prf or wallet_pin.
Responses
200Default Response
Schema
okrequiredboolean
e.g. true
addressrequiredstring
e.g. "0x..."
tokenrequiredstring
JWT authentication token
accountIdrequiredstring | null
Account ID if user is registered, null otherwise
json
{
  "ok": true,
  "address": "0x...",
  "token": "string",
  "accountId": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
422Default Response
Schema
errorrequiredstring
e.g. "Unprocessable Entity"
messagerequiredstring
codestring
e.g. "UNPROCESSABLE_ENTITY"
json
{
  "error": "Unprocessable Entity",
  "message": "string",
  "code": "UNPROCESSABLE_ENTITY"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 10 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 10 requests per 1 minute."
}
Try it
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "message": "",
  "signature": "",
  "authType": ""
}' \
  "https://api-stg.clkd.xyz/v1/verify"

Logout

POST/v1/logout

Clear the server-side cache for the authenticated user. JWT tokens are stateless, so the client should also discard the token. Auth is optional — unauthenticated calls succeed without clearing any cache.

Responses
200Default Response
Schema
okrequiredboolean
e.g. true
json
{
  "ok": true
}
Try it
curl -X POST \
  "https://api-stg.clkd.xyz/v1/logout"

Account Management

Account creation, signers, subdomains, and setup

Check subdomain availability

GET/v1/subdomain/check

Check whether a subdomain name is available for registration. Public endpoint — no authentication required. Use before calling setSubdomain to avoid conflicts.

Parameters
NameInTypeDescription
name*querystring—
inviteCodequerystring—
Responses
200Default Response
Schema
availablerequiredboolean
reason"taken" | "blocked"
json
{
  "available": true,
  "reason": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
Try it
Query Parameters
name
inviteCode
curl -X GET \
  "https://api-stg.clkd.xyz/v1/subdomain/check"

Get referral availability

GET/v1/referrals/availability

Check whether referral links may be accepted or generated for the current request location.

Responses
200Default Response
Schema
availablerequiredboolean
json
{
  "available": true
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 30 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 30 requests per 1 minute."
}
Try it
curl -X GET \
  "https://api-stg.clkd.xyz/v1/referrals/availability"

Get referral preview

GET/v1/referrals/{code}/preview

Return the public display name and current terms for an eligible referral link.

Parameters
NameInTypeDescription
code*pathstring—
Responses
200Default Response
Schema
referrerNamerequiredstring | null
referrerShareBpsrequiredinteger
referredDiscountBpsrequiredinteger
earningDurationDaysrequiredinteger
minimumRewardUsdCentsrequiredinteger
json
{
  "referrerName": "string",
  "referrerShareBps": null,
  "referredDiscountBps": null,
  "earningDurationDays": null,
  "minimumRewardUsdCents": null
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 30 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 30 requests per 1 minute."
}
Try it
Path Parameters
code
curl -X GET \
  "https://api-stg.clkd.xyz/v1/referrals/{code}/preview"

Create account

POST/v1/accounts/🔒

Register a new account by submitting HPKE-encrypted key material. The caller must already have a JWT from the SIWE sign-in flow, which proves ownership of the Ethereum address. The server decrypts and stores the keys, enabling payment address generation for this account. Requires an invite code when gated access is enabled. Returns the new accountId, or indicates if the address already has an account.

Request Body
ciphertextrequiredstring
Base64-encoded encrypted payload
encapsulatedKeyrequiredstring
Base64-encoded HPKE encapsulated key
inviteCodestring
Invite code for gated access
onboardingExperimentIdstring (uuid)
experimentKeystring
variantKeystring
referralCodestring
Responses
201Default Response
Schema
accountIdrequiredstring | null
Created account ID (null if already existed)
alreadyExistedrequiredboolean
referralAppliedrequiredboolean
Whether the newly created account was atomically attributed to the supplied referral
json
{
  "accountId": "string",
  "alreadyExisted": true,
  "referralApplied": true
}
409Default Response
Schema
errorrequiredstring
e.g. "Conflict"
messagerequiredstring
codestring
e.g. "QUOTE_LOCK_CONFLICT"
json
{
  "error": "Conflict",
  "message": "string",
  "code": "QUOTE_LOCK_CONFLICT"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "ciphertext": "",
  "encapsulatedKey": "",
  "inviteCode": "",
  "onboardingExperimentId": "",
  "experimentKey": "",
  "variantKey": "",
  "referralCode": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/"

Get account

GET/v1/accounts/{accountId}🔒

Retrieve account metadata including the owner address, registration status, and ENS subdomain. Useful for determining onboarding state (e.g., whether the user still needs to claim a subdomain).

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
accountIdrequiredstring
addressrequiredstring | null
isRegisteredrequiredboolean
createdAtrequiredstring | null
Timestamp when the account was created.
subdomainrequiredstring | null
encryptedCustomEnsNamerequiredstring | null
activationOfferClaimExpiresAtrequiredstring | null
Timestamp when the new-user activation offer can no longer be claimed.
lastConsumedNoncerequirednumber | null
Last consumed stealth address nonce (0-indexed). null if no addresses generated yet.
cloakieobject | null
hasPoolDepositsboolean
True if the account has any pool commitment rows. Used to trigger eager pool balance discovery at login.
dismissedProfilePromptsrequiredstring[]
Profile prompts permanently dismissed for this account across browsers and devices.
json
{
  "accountId": "string",
  "address": "string",
  "isRegistered": true,
  "createdAt": "string",
  "subdomain": "string",
  "encryptedCustomEnsName": "string",
  "activationOfferClaimExpiresAt": "string",
  "lastConsumedNonce": 0,
  "cloakie": {
    "active": true,
    "deposits": [
      {
        "tokenId": "string",
        "imageUrl": "string",
        "depositAddress": "string"
      }
    ]
  },
  "hasPoolDeposits": true,
  "dismissedProfilePrompts": [
    "string"
  ]
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}"

Get dapp addresses

GET/v1/accounts/{accountId}/dapp-addresses🔒

List addresses used in successful onchain browser-extension dApp actions.

Parameters
NameInTypeDescription
limitqueryinteger—
offsetqueryinteger—
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
itemsrequiredobject[]
addressrequiredstring
apprequiredobject
originrequiredstring
displayNamerequiredstring
iconUrlrequiredstring | null
lastUsedAtrequiredstring (date-time)
hasMorerequiredboolean
json
{
  "items": [
    {
      "address": "string",
      "app": {
        "origin": "string",
        "displayName": "string",
        "iconUrl": "string"
      },
      "lastUsedAt": "string"
    }
  ],
  "hasMore": true
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
Query Parameters
limit
offset
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/dapp-addresses"

Get address ownership

GET/v1/accounts/{accountId}/address-ownership🔒

Check whether an Ethereum address belongs to the authenticated account.

Parameters
NameInTypeDescription
address*querystring—
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
ownedrequiredboolean
json
{
  "owned": true
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
Query Parameters
address
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/address-ownership"

List account tokens

GET/v1/accounts/{accountId}/tokens🔒

List active token imports for the authenticated account.

Parameters
NameInTypeDescription
includequerystringComma-separated optional enrichments. Supported values: market,sources.
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
tokensrequiredobject[]
addressrequiredstring
symbolrequiredstring
namerequiredstring
decimalsrequirednumber
chainIdrequirednumber
logoURIstring
isClankerboolean
visibilitystring
metadataSourcestring
marketobject | null
sourcesobject[]
sourcerequiredstring
sourceIdrequiredstring
namestring
symbolstring
decimalsnumber
logoUrlstring
externalUrlstring
firstSeenAtrequiredstring
lastSeenAtrequiredstring
json
{
  "tokens": [
    {
      "address": "string",
      "symbol": "string",
      "name": "string",
      "decimals": 0,
      "chainId": 0,
      "logoURI": "string",
      "isClanker": true,
      "visibility": "string",
      "metadataSource": "string",
      "market": {
        "provider": "string",
        "providerAssetId": "string",
        "vsCurrency": "string",
        "price": "string",
        "marketCap": "string",
        "marketCapRank": 0,
        "fullyDilutedValuation": "string",
        "totalVolume": "string",
        "high24h": "string",
        "low24h": "string",
        "priceChange24h": "string",
        "priceChangePercentage24h": "string",
        "marketCapChange24h": "string",
        "marketCapChangePercentage24h": "string",
        "circulatingSupply": "string",
        "totalSupply": "string",
        "maxSupply": "string",
        "ath": "string",
        "athChangePercentage": "string",
        "athDate": "string",
        "atl": "string",
        "atlChangePercentage": "string",
        "atlDate": "string",
        "providerUpdatedAt": "string",
        "fetchedAt": "string",
        "stale": true
      },
      "sources": [
        {
          "source": "string",
          "sourceId": "string",
          "name": "string",
          "symbol": "string",
          "decimals": 0,
          "logoUrl": "string",
          "externalUrl": "string",
          "firstSeenAt": "string",
          "lastSeenAt": "string"
        }
      ]
    }
  ]
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
Try it
Path Parameters
accountId
Query Parameters
include
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/tokens"

Import account token

POST/v1/accounts/{accountId}/tokens🔒

Import an allowed canonical token for the authenticated account.

Parameters
NameInTypeDescription
includequerystringComma-separated optional enrichments. Supported values: market,sources.
accountId*pathstring (uuid)Account ID
Request Body
chainIdrequirednumber
addressrequiredstring
Responses
200Default Response
Schema
tokenrequiredobject
addressrequiredstring
symbolrequiredstring
namerequiredstring
decimalsrequirednumber
chainIdrequirednumber
logoURIstring
isClankerboolean
visibilitystring
metadataSourcestring
marketobject | null
sourcesobject[]
sourcerequiredstring
sourceIdrequiredstring
namestring
symbolstring
decimalsnumber
logoUrlstring
externalUrlstring
firstSeenAtrequiredstring
lastSeenAtrequiredstring
json
{
  "token": {
    "address": "string",
    "symbol": "string",
    "name": "string",
    "decimals": 0,
    "chainId": 0,
    "logoURI": "string",
    "isClanker": true,
    "visibility": "string",
    "metadataSource": "string",
    "market": {
      "provider": "string",
      "providerAssetId": "string",
      "vsCurrency": "string",
      "price": "string",
      "marketCap": "string",
      "marketCapRank": 0,
      "fullyDilutedValuation": "string",
      "totalVolume": "string",
      "high24h": "string",
      "low24h": "string",
      "priceChange24h": "string",
      "priceChangePercentage24h": "string",
      "marketCapChange24h": "string",
      "marketCapChangePercentage24h": "string",
      "circulatingSupply": "string",
      "totalSupply": "string",
      "maxSupply": "string",
      "ath": "string",
      "athChangePercentage": "string",
      "athDate": "string",
      "atl": "string",
      "atlChangePercentage": "string",
      "atlDate": "string",
      "providerUpdatedAt": "string",
      "fetchedAt": "string",
      "stale": true
    },
    "sources": [
      {
        "source": "string",
        "sourceId": "string",
        "name": "string",
        "symbol": "string",
        "decimals": 0,
        "logoUrl": "string",
        "externalUrl": "string",
        "firstSeenAt": "string",
        "lastSeenAt": "string"
      }
    ]
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 10 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 10 requests per 1 minute."
}
Try it
Path Parameters
accountId
Query Parameters
include
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "chainId": 0,
  "address": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/tokens"

Get account token detail

GET/v1/accounts/{accountId}/tokens/{chainId}/{address}🔒

Return canonical token metadata and this account’s balance for one token. Use include=market,sources to attach current market data and provider provenance.

Parameters
NameInTypeDescription
includequerystringComma-separated optional enrichments. Supported values: market,sources.
accountId*pathstring (uuid)Account ID
chainId*pathstringChain ID
address*pathstringToken contract address
Responses
200Default Response
Schema
tokenrequiredobject
addressrequiredstring
symbolrequiredstring
namerequiredstring
decimalsrequirednumber
chainIdrequirednumber
logoURIstring
isClankerboolean
visibilitystring
metadataSourcestring
marketobject | null
sourcesobject[]
sourcerequiredstring
sourceIdrequiredstring
namestring
symbolstring
decimalsnumber
logoUrlstring
externalUrlstring
firstSeenAtrequiredstring
lastSeenAtrequiredstring
balancerequiredobject
Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.
chainIdrequirednumber
Chain ID where this token resides
chainNamerequiredstring
Human-readable chain name
tokenrequiredstring
Token contract address (EIP-55 checksummed)
tokenSymbolrequiredstring
Token ticker symbol
decimalsrequirednumber
Token decimal places
logoUrlrequiredstring | null
Token logo URL, or null if unavailable
visiblerequiredobject
Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.
availablerequiredstring
Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)
pendingrequiredstring
Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)
incognitorequiredobject
Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.
pooledrequiredobject
Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.
availablerequiredstring
Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)
pendingApprovalrequiredstring
Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)
pendingWithdrawalrequiredstring
ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)
declinedrequiredstring
Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)
usdAmountrequirednumber | null
Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.
pricePerTokenrequirednumber | null
USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.
priceStalerequiredboolean
True when the price is older than the configured fresh-cache lifetime
spamrequiredboolean
True if the token is flagged as potential spam or a phishing token
json
{
  "token": {
    "address": "string",
    "symbol": "string",
    "name": "string",
    "decimals": 0,
    "chainId": 0,
    "logoURI": "string",
    "isClanker": true,
    "visibility": "string",
    "metadataSource": "string",
    "market": {
      "provider": "string",
      "providerAssetId": "string",
      "vsCurrency": "string",
      "price": "string",
      "marketCap": "string",
      "marketCapRank": 0,
      "fullyDilutedValuation": "string",
      "totalVolume": "string",
      "high24h": "string",
      "low24h": "string",
      "priceChange24h": "string",
      "priceChangePercentage24h": "string",
      "marketCapChange24h": "string",
      "marketCapChangePercentage24h": "string",
      "circulatingSupply": "string",
      "totalSupply": "string",
      "maxSupply": "string",
      "ath": "string",
      "athChangePercentage": "string",
      "athDate": "string",
      "atl": "string",
      "atlChangePercentage": "string",
      "atlDate": "string",
      "providerUpdatedAt": "string",
      "fetchedAt": "string",
      "stale": true
    },
    "sources": [
      {
        "source": "string",
        "sourceId": "string",
        "name": "string",
        "symbol": "string",
        "decimals": 0,
        "logoUrl": "string",
        "externalUrl": "string",
        "firstSeenAt": "string",
        "lastSeenAt": "string"
      }
    ]
  },
  "balance": {
    "chainId": 8453,
    "chainName": "Base",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "tokenSymbol": "USDC",
    "decimals": 6,
    "logoUrl": "https://assets.coingecko.com/coins/images/6319/small/usdc.png",
    "visible": {
      "available": "1000000",
      "pending": "500000"
    },
    "incognito": {
      "pooled": {
        "available": "750000",
        "pendingApproval": "250000",
        "pendingWithdrawal": "500000",
        "declined": "0"
      }
    },
    "usdAmount": 1.5,
    "pricePerToken": 2000.42,
    "priceStale": false,
    "spam": false
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
chainId
address
Query Parameters
include
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/tokens/{chainId}/{address}"

Claim subdomain

POST/v1/accounts/{accountId}/subdomain🔒

Claim an ENS subdomain (e.g. alice.clkd.eth) for this account so senders can pay via a human-readable name instead of a raw address. Each account may claim one subdomain.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
subdomainrequiredstring
Subdomain name (will be normalized and stored as {subdomain}.clkd.eth)
Responses
200Default Response
Schema
successrequiredboolean
messagerequiredstring
subdomainrequiredstring
json
{
  "success": true,
  "message": "string",
  "subdomain": "string"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "subdomain": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/subdomain"

Generate subdomain

GET/v1/accounts/{accountId}/subdomain/generate🔒

Generate a random available subdomain for the user to preview during onboarding. The name is not reserved — call setSubdomain to claim it.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
subdomainrequiredstring
e.g. "example-123.clkd.eth"
json
{
  "subdomain": "example-123.clkd.eth"
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/subdomain/generate"

Get account referral attribution

GET/v1/accounts/{accountId}/referrals/attribution🔒

Return this account's referral relationship, including its snapshotted terms and current status.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
referrerNamerequiredstring | null
referrerShareBpsrequiredinteger
referredDiscountBpsrequiredinteger
minimumRewardUsdCentsrequiredinteger
earningStartsAtrequiredstring (date-time)
earningEndsAtrequiredstring (date-time)
revokedAtrequiredstring | null
statusrequired"active" | "ended" | "expired"
json
{
  "referrerName": "string",
  "referrerShareBps": null,
  "referredDiscountBps": null,
  "minimumRewardUsdCents": null,
  "earningStartsAt": "string",
  "earningEndsAt": "string",
  "revokedAt": "string",
  "status": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/referrals/attribution"

End account referral attribution

DELETE/v1/accounts/{accountId}/referrals/attribution🔒

Permanently end this account's future referral discount and its referrer's future fee share.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
referrerNamerequiredstring | null
referrerShareBpsrequiredinteger
referredDiscountBpsrequiredinteger
minimumRewardUsdCentsrequiredinteger
earningStartsAtrequiredstring (date-time)
earningEndsAtrequiredstring (date-time)
revokedAtrequiredstring | null
statusrequired"active" | "ended" | "expired"
json
{
  "referrerName": "string",
  "referrerShareBps": null,
  "referredDiscountBps": null,
  "minimumRewardUsdCents": null,
  "earningStartsAt": "string",
  "earningEndsAt": "string",
  "revokedAt": "string",
  "status": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X DELETE \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/referrals/attribution"

Get referrals made summary

GET/v1/accounts/{accountId}/referrals/summary🔒

Return aggregate referral counts and successfully paid reward value without identifying referred accounts or their activity.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
totalReferralsrequiredinteger
activeReferralsrequiredinteger
totalEarnedUsdrequiredstring | null
json
{
  "totalReferrals": null,
  "activeReferrals": null,
  "totalEarnedUsd": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/referrals/summary"

Get or create referral profile

POST/v1/accounts/{accountId}/referrals/profile🔒

Return the account's active referral profile, creating its standard member profile on first use.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
coderequiredstring
referrerShareBpsrequiredinteger
referredDiscountBpsrequiredinteger
earningDurationDaysrequiredinteger
minimumRewardUsdCentsrequiredinteger
json
{
  "code": "string",
  "referrerShareBps": null,
  "referredDiscountBps": null,
  "earningDurationDays": null,
  "minimumRewardUsdCents": null
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X POST \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/referrals/profile"

Receive

Payment address generation and ENS resolution

Create payment address

POST/v1/accounts/{accountId}/payment-address🔒

Derive a one-time payment address so a sender can transfer tokens to this account without revealing the recipient on-chain.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
idempotency-keyheaderstringClient-generated key for one account, HTTP operation, and exact request body. Reuse it only to retry that same operation; a completed retry returns the stored response. Keys expire after 24 hours.
Request Body
Responses
201Default Response
Schema
addressrequiredstring
noncerequiredstring
Nonce used for derivation (stringified bigint)
reusedboolean
True when the daily limit is reached and a previously-issued address is served instead of a fresh one.
limitResetsAtstring
ISO timestamp (next UTC midnight) when fresh addresses become available again. Present only when reused is true.
json
{
  "address": "string",
  "nonce": "string",
  "reused": true,
  "limitResetsAt": "string"
}
Try it
Path Parameters
accountId
Headers
idempotency-key
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/payment-address"

Balance & Activity

Balance queries, transaction history, and supported tokens

List supported chains

GET/v1/supported-chains

List every chain the platform supports, including explorer URLs, logo base names, and testnet/mainnet mapping. Use to populate chain pickers or build explorer links.

Responses
200Default Response
Schema (item)
namerequiredstring
chainIdrequirednumber
isTestnetrequiredboolean
explorerUrlrequiredstring
explorerTxPathrequiredstring
mainnetChainIdrequirednumber
logoBaseNamerequiredstring
isSquareLogorequiredboolean
json
[
  {
    "name": "string",
    "chainId": 0,
    "isTestnet": true,
    "explorerUrl": "string",
    "explorerTxPath": "string",
    "mainnetChainId": 0,
    "logoBaseName": "string",
    "isSquareLogo": true
  }
]
Try it
curl -X GET \
  "https://api-stg.clkd.xyz/v1/supported-chains"

Get token catalog

GET/v1/token-catalog

Public, read-only access to the existing supported token catalog, pinned symbols for the swap picker, and testnet-to-mainnet chain-ID mapping. This endpoint never discovers tokens or persists token data.

Parameters
NameInTypeDescription
qquerystring—
chainIdquerynumber—
limitquerynumber—
cursorquerystring—
includequerystringComma-separated optional enrichments. Supported values: market,sources.
Responses
200Default Response
Schema
tokensrequiredobject[]
addressrequiredstring
symbolrequiredstring
namerequiredstring
decimalsrequirednumber
chainIdrequirednumber
logoURIstring
isClankerboolean
visibilitystring
metadataSourcestring
marketobject | null
sourcesobject[]
sourcerequiredstring
sourceIdrequiredstring
namestring
symbolstring
decimalsnumber
logoUrlstring
externalUrlstring
firstSeenAtrequiredstring
lastSeenAtrequiredstring
pinnedSymbolsrequiredstring[]
testnetToMainnetrequiredobject
nextCursorstring
json
{
  "tokens": [
    {
      "address": "string",
      "symbol": "string",
      "name": "string",
      "decimals": 0,
      "chainId": 0,
      "logoURI": "string",
      "isClanker": true,
      "visibility": "string",
      "metadataSource": "string",
      "market": {
        "provider": "string",
        "providerAssetId": "string",
        "vsCurrency": "string",
        "price": "string",
        "marketCap": "string",
        "marketCapRank": 0,
        "fullyDilutedValuation": "string",
        "totalVolume": "string",
        "high24h": "string",
        "low24h": "string",
        "priceChange24h": "string",
        "priceChangePercentage24h": "string",
        "marketCapChange24h": "string",
        "marketCapChangePercentage24h": "string",
        "circulatingSupply": "string",
        "totalSupply": "string",
        "maxSupply": "string",
        "ath": "string",
        "athChangePercentage": "string",
        "athDate": "string",
        "atl": "string",
        "atlChangePercentage": "string",
        "atlDate": "string",
        "providerUpdatedAt": "string",
        "fetchedAt": "string",
        "stale": true
      },
      "sources": [
        {
          "source": "string",
          "sourceId": "string",
          "name": "string",
          "symbol": "string",
          "decimals": 0,
          "logoUrl": "string",
          "externalUrl": "string",
          "firstSeenAt": "string",
          "lastSeenAt": "string"
        }
      ]
    }
  ],
  "pinnedSymbols": [
    "string"
  ],
  "testnetToMainnet": null,
  "nextCursor": "string"
}
Try it
Query Parameters
q
chainId
limit
cursor
include
curl -X GET \
  "https://api-stg.clkd.xyz/v1/token-catalog"

Lookup token

GET/v1/token-lookup🔒

Look up token metadata by contract address for an authenticated account. Checks cached sources first, then may query trusted token providers and on-chain ERC-20 metadata and persist newly discovered sources.

Parameters
NameInTypeDescription
address*querystring—
chainId*querynumber—
includequerystringComma-separated optional enrichments. Supported values: market,sources.
Responses
200Default Response
Schema
addressrequiredstring
symbolrequiredstring
namerequiredstring
decimalsrequirednumber
chainIdrequirednumber
logoURIstring
isClankerboolean
visibilitystring
metadataSourcestring
marketobject | null
sourcesobject[]
sourcerequiredstring
sourceIdrequiredstring
namestring
symbolstring
decimalsnumber
logoUrlstring
externalUrlstring
firstSeenAtrequiredstring
lastSeenAtrequiredstring
json
{
  "address": "string",
  "symbol": "string",
  "name": "string",
  "decimals": 0,
  "chainId": 0,
  "logoURI": "string",
  "isClanker": true,
  "visibility": "string",
  "metadataSource": "string",
  "market": {
    "provider": "string",
    "providerAssetId": "string",
    "vsCurrency": "string",
    "price": "string",
    "marketCap": "string",
    "marketCapRank": 0,
    "fullyDilutedValuation": "string",
    "totalVolume": "string",
    "high24h": "string",
    "low24h": "string",
    "priceChange24h": "string",
    "priceChangePercentage24h": "string",
    "marketCapChange24h": "string",
    "marketCapChangePercentage24h": "string",
    "circulatingSupply": "string",
    "totalSupply": "string",
    "maxSupply": "string",
    "ath": "string",
    "athChangePercentage": "string",
    "athDate": "string",
    "atl": "string",
    "atlChangePercentage": "string",
    "atlDate": "string",
    "providerUpdatedAt": "string",
    "fetchedAt": "string",
    "stale": true
  },
  "sources": [
    {
      "source": "string",
      "sourceId": "string",
      "name": "string",
      "symbol": "string",
      "decimals": 0,
      "logoUrl": "string",
      "externalUrl": "string",
      "firstSeenAt": "string",
      "lastSeenAt": "string"
    }
  ]
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
Try it
Query Parameters
address
chainId
include
curl -X GET \
  "https://api-stg.clkd.xyz/v1/token-lookup"

Get balances

GET/v1/accounts/{accountId}/balance🔒

Retrieve token balances across every supported chain for this account. Each balance contains visible (standard on-chain) available and pending amounts. Returns a totalUsdAmount summarizing all holdings.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
balancesrequiredobject[]
One entry per token per chain, each with tiered balance breakdown
chainIdrequirednumber
Chain ID where this token resides
chainNamerequiredstring
Human-readable chain name
tokenrequiredstring
Token contract address (EIP-55 checksummed)
tokenSymbolrequiredstring
Token ticker symbol
decimalsrequirednumber
Token decimal places
logoUrlrequiredstring | null
Token logo URL, or null if unavailable
visiblerequiredobject
Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.
availablerequiredstring
Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)
pendingrequiredstring
Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)
incognitorequiredobject
Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.
pooledrequiredobject
Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.
availablerequiredstring
Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)
pendingApprovalrequiredstring
Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)
pendingWithdrawalrequiredstring
ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)
declinedrequiredstring
Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)
usdAmountrequirednumber | null
Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.
pricePerTokenrequirednumber | null
USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.
priceStalerequiredboolean
True when the price is older than the configured fresh-cache lifetime
spamrequiredboolean
True if the token is flagged as potential spam or a phishing token
totalUsdAmountrequirednumber | null
Sum of usdAmount across all balance items. Null when no pricing data is available for any token.
feeWaiverrequiredobject
activerequiredboolean
True when Cloaked service fees are currently waived for this account.
sourcerequired"activation" | "cloakie" | null
Why fees are waived. activation is the time-limited new-user activation offer; cloakie is the NFT waiver.
activeUntilrequiredstring | null
Expiry timestamp for time-limited waivers. Null for non-expiring waivers.
json
{
  "balances": [
    {
      "chainId": 8453,
      "chainName": "Base",
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenSymbol": "USDC",
      "decimals": 6,
      "logoUrl": "https://assets.coingecko.com/coins/images/6319/small/usdc.png",
      "visible": {
        "available": "1000000",
        "pending": "500000"
      },
      "incognito": {
        "pooled": {
          "available": "750000",
          "pendingApproval": "250000",
          "pendingWithdrawal": "500000",
          "declined": "0"
        }
      },
      "usdAmount": 1.5,
      "pricePerToken": 2000.42,
      "priceStale": false,
      "spam": false
    }
  ],
  "totalUsdAmount": 1.5,
  "feeWaiver": {
    "active": true,
    "source": "string",
    "activeUntil": "string"
  }
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/balance"

Get chain balances

GET/v1/accounts/{accountId}/balance/{chainId}🔒

Retrieve token balances filtered to a single chain. Same response shape as getBalances (visible available/pending) but scoped to the given chainId.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
chainId*pathstringChain ID (e.g., 8453 for Base)
Responses
200Default Response
Schema
balancesrequiredobject[]
One entry per token per chain, each with tiered balance breakdown
chainIdrequirednumber
Chain ID where this token resides
chainNamerequiredstring
Human-readable chain name
tokenrequiredstring
Token contract address (EIP-55 checksummed)
tokenSymbolrequiredstring
Token ticker symbol
decimalsrequirednumber
Token decimal places
logoUrlrequiredstring | null
Token logo URL, or null if unavailable
visiblerequiredobject
Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.
availablerequiredstring
Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)
pendingrequiredstring
Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)
incognitorequiredobject
Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.
pooledrequiredobject
Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.
availablerequiredstring
Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)
pendingApprovalrequiredstring
Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)
pendingWithdrawalrequiredstring
ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)
declinedrequiredstring
Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)
usdAmountrequirednumber | null
Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.
pricePerTokenrequirednumber | null
USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.
priceStalerequiredboolean
True when the price is older than the configured fresh-cache lifetime
spamrequiredboolean
True if the token is flagged as potential spam or a phishing token
totalUsdAmountrequirednumber | null
Sum of usdAmount across all balance items. Null when no pricing data is available for any token.
feeWaiverrequiredobject
activerequiredboolean
True when Cloaked service fees are currently waived for this account.
sourcerequired"activation" | "cloakie" | null
Why fees are waived. activation is the time-limited new-user activation offer; cloakie is the NFT waiver.
activeUntilrequiredstring | null
Expiry timestamp for time-limited waivers. Null for non-expiring waivers.
json
{
  "balances": [
    {
      "chainId": 8453,
      "chainName": "Base",
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenSymbol": "USDC",
      "decimals": 6,
      "logoUrl": "https://assets.coingecko.com/coins/images/6319/small/usdc.png",
      "visible": {
        "available": "1000000",
        "pending": "500000"
      },
      "incognito": {
        "pooled": {
          "available": "750000",
          "pendingApproval": "250000",
          "pendingWithdrawal": "500000",
          "declined": "0"
        }
      },
      "usdAmount": 1.5,
      "pricePerToken": 2000.42,
      "priceStale": false,
      "spam": false
    }
  ],
  "totalUsdAmount": 1.5,
  "feeWaiver": {
    "active": true,
    "source": "string",
    "activeUntil": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
chainId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/balance/{chainId}"

Get token balance

GET/v1/accounts/{accountId}/balance/{chainId}/{token}🔒

Retrieve the balance for a single token on a specific chain. Returns visible available and pending amounts. Returns a zero-balance object if the token has never been received.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
chainId*pathstringChain ID
token*pathstringToken address (0x...)
Responses
200Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.
Schema
chainIdrequirednumber
Chain ID where this token resides
chainNamerequiredstring
Human-readable chain name
tokenrequiredstring
Token contract address (EIP-55 checksummed)
tokenSymbolrequiredstring
Token ticker symbol
decimalsrequirednumber
Token decimal places
logoUrlrequiredstring | null
Token logo URL, or null if unavailable
visiblerequiredobject
Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.
availablerequiredstring
Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)
pendingrequiredstring
Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)
incognitorequiredobject
Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.
pooledrequiredobject
Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.
availablerequiredstring
Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)
pendingApprovalrequiredstring
Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)
pendingWithdrawalrequiredstring
ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)
declinedrequiredstring
Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)
usdAmountrequirednumber | null
Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.
pricePerTokenrequirednumber | null
USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.
priceStalerequiredboolean
True when the price is older than the configured fresh-cache lifetime
spamrequiredboolean
True if the token is flagged as potential spam or a phishing token
json
{
  "chainId": 8453,
  "chainName": "Base",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "tokenSymbol": "USDC",
  "decimals": 6,
  "logoUrl": "https://assets.coingecko.com/coins/images/6319/small/usdc.png",
  "visible": {
    "available": "1000000",
    "pending": "500000"
  },
  "incognito": {
    "pooled": {
      "available": "750000",
      "pendingApproval": "250000",
      "pendingWithdrawal": "500000",
      "declined": "0"
    }
  },
  "usdAmount": 1.5,
  "pricePerToken": 2000.42,
  "priceStale": false,
  "spam": false
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
chainId
token
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/balance/{chainId}/{token}"

Get activities

GET/v1/accounts/{accountId}/activities🔒

List confirmed (on-chain) transactions for the account with cursor-based pagination. The response uses a discriminated union on kind: SEND/RECEIVE/SELF/INCOGNITO_*/NFT_WITHDRAW/DAPP_CALL include a transfers array, SWAP includes a swap object with source and dest token info, BRIDGE and CROSS_CHAIN_SWAP include a bridge object with source, dest, and chain info. For in-flight transactions, use GET /activities/pending.

Parameters
NameInTypeDescription
limitquerystringMaximum number of activities to return (1-500, default: 100)
cursorquerystringBase64-encoded cursor for pagination
hideLikelySpamqueryanyWhen true, likely spam activities are filtered before applying the page limit.
addressquerystringOwned address to scope the activity feed to.
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
provenanceLabelGroupsrequiredobject
activityrequiredobject[]
txHashrequiredstring | null
quoteIdstring (uuid)
Quote ID that produced this transaction, for correlating pending → confirmed
chainIdrequirednumber
e.g. 8453
chainNamerequiredstring
e.g. "Base"
explorerTxUrlBaserequiredstring | null
Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.
daterequiredstring (date-time)
kindrequired"SEND" | "RECEIVE" | "SELF" | "SWAP" | "BRIDGE" | "CROSS_CHAIN_SWAP" | "POOL_DEPOSIT" | "POOL_RECOVER" | "INCOGNITO_SEND" | "INCOGNITO_SELF_SEND" | "NFT_WITHDRAW" | "DAPP_CALL"
lifecyclerequiredobject | object | object
isExternalrequiredboolean
True for indexed no-intent transactions signed directly by one of the account's addresses.
isLikelySpamrequiredboolean
e.g. false
feesrequiredobject[]
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 18
tokenSymbolrequiredstring
e.g. "ETH"
logoUrlrequiredstring | null
valuerequiredstring
e.g. "1000000000000000"
usdAmountrequirednumber | null
USD value of the fee, or null when token USD pricing is unavailable.
cloakedFeeBpsnumber | null
sourceProvenanceobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
fundingAddressesstring[]
Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.
transfersobject[]
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 6
tokenSymbolrequiredstring
e.g. "USDC"
logoUrlrequiredstring | null
fromAddressrequiredstring
e.g. "0x..."
toAddressrequiredstring
e.g. "0x..."
valuerequiredstring
e.g. "1000000"
usdAmountrequirednumber | null
USD value of the transfer, or null when token USD pricing is unavailable.
provenanceobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
swapobject
sourceTokenAddressrequiredstring
e.g. "0x..."
sourceDecimalsrequirednumber
e.g. 6
sourceTokenSymbolrequiredstring
e.g. "USDC"
sourceLogoUrlrequiredstring | null
sourceAmountrequiredstring
e.g. "1000000"
sourceUsdAmountrequirednumber | null
USD value of the source amount, or null when token USD pricing is unavailable.
destTokenAddressrequiredstring
e.g. "0x..."
destTokenSymbolrequiredstring
e.g. "WETH"
destDecimalsrequirednumber
e.g. 18
destLogoUrlrequiredstring | null
destAmountrequiredstring
e.g. "500000000000000"
destUsdAmountrequirednumber | null
USD value of the destination amount, or null when token USD pricing is unavailable.
outputRecipientrequiredstring
e.g. "0x..."
outputRecipientIsOwnAddressboolean
Whether the output recipient belongs to the Cloaked account that owns this activity.
bridgeobject
sourceTokenAddressrequiredstring
e.g. "0x..."
sourceDecimalsrequirednumber
e.g. 6
sourceTokenSymbolrequiredstring
e.g. "USDC"
sourceLogoUrlrequiredstring | null
sourceAmountrequiredstring
e.g. "1000000"
sourceUsdAmountrequirednumber | null
USD value of the source amount, or null when token USD pricing is unavailable.
destTokenAddressrequiredstring
e.g. "0x..."
destTokenSymbolrequiredstring
e.g. "USDC"
destDecimalsrequirednumber
e.g. 6
destLogoUrlrequiredstring | null
destAmountrequiredstring
e.g. "1000000"
destUsdAmountrequirednumber | null
USD value of the destination amount, or null when token USD pricing is unavailable.
outputRecipientrequiredstring
e.g. "0x..."
outputRecipientIsOwnAddressboolean
Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.
bridgeStatusrequiredstring
e.g. "pending"
destChainIdrequirednumber
e.g. 8453
destChainNamerequiredstring
e.g. "Base"
destExplorerTxUrlBaserequiredstring | null
Explorer tx URL prefix for the destination chain; append destTxHash.
estimatedFillTimeMsrequirednumber | null
destTxHashrequiredstring | null
refundTxHashrequiredstring | null
refundEligibleAtrequiredstring | null
poolobject
poolAddressrequiredstring
e.g. "0x..."
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 18
tokenSymbolrequiredstring
e.g. "ETH"
logoUrlrequiredstring | null
amountrequiredstring
e.g. "1000000000000000"
usdAmountrequirednumber | null
USD value of the pool amount, or null when token USD pricing is unavailable.
aspStatus"pending" | "approved" | "declined" | "failed" | "cancelled"
commitmentIdstring
vettingFeestring
vettingFeeUsdnumber | null
depositFeestring
depositFeeUsdnumber | null
dappMetaobject
originstring
descriptionstring
iconUrlstring
connectedAddressstring
isAccountSetupboolean
calldatastring
Raw calls JSON for dapp-call activities: [{ to, value, data }]
paginationrequiredobject
limitrequirednumber
e.g. 100
nextCursorrequiredstring | null
Base64-encoded cursor for next page
json
{
  "provenanceLabelGroups": null,
  "activity": [
    {
      "txHash": "0x...",
      "quoteId": "string",
      "chainId": 8453,
      "chainName": "Base",
      "explorerTxUrlBase": "https://basescan.org/tx/",
      "date": "string",
      "kind": "string",
      "lifecycle": {
        "state": "string"
      },
      "isExternal": false,
      "isLikelySpam": false,
      "fees": [
        {
          "tokenAddress": "0x...",
          "decimals": 18,
          "tokenSymbol": "ETH",
          "logoUrl": "string",
          "value": "1000000000000000",
          "usdAmount": 0.001
        }
      ],
      "cloakedFeeBps": 0,
      "sourceProvenance": {
        "status": "string",
        "outputSystemTags": [
          {
            "type": "string",
            "provider": "string",
            "text": "string",
            "explanationKey": "string",
            "evidence": {
              "chainId": null,
              "txHash": "string",
              "transferOrLogIndex": null,
              "receiveFromAddress": "string",
              "poolAddress": "string",
              "entrypointAddress": "string",
              "poolTransferOrLogIndex": null
            }
          }
        ],
        "sourceLabelGroupId": "string",
        "olderFundsCount": null,
        "unresolvedReasons": [
          "string"
        ],
        "displayContext": {
          "reason": "string",
          "currentOutputCount": null,
          "sourceCount": null,
          "actionTypes": [
            "string"
          ]
        },
        "funding": {
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ]
        },
        "association": {
          "status": "string",
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ],
          "ignoredUnsolicitedCount": null,
          "summary": {
            "sourceCount": null,
            "userTaggedSourceCount": null,
            "untaggedSourceCount": null,
            "olderFundsCount": null,
            "unknownCount": null
          }
        },
        "display": {
          "badgeKind": "string",
          "label": "string",
          "fundingLabel": "string",
          "associationLabel": "string"
        },
        "editableSource": {
          "id": "string",
          "kind": "string",
          "origin": {
            "chainId": null,
            "txHash": "string",
            "transferOrLogIndex": null
          },
          "address": "string",
          "tagPayloadCiphertext": "string",
          "tagPayloadUpdatedAt": "string",
          "tagEligibility": "string",
          "tagEditable": true,
          "systemTags": [
            {
              "type": "string",
              "text": "string",
              "explanationKey": "string",
              "evidence": {
                "address": "string",
                "origins": [
                  {
                    "origin": "string",
                    "displayName": "string",
                    "iconUrl": "string",
                    "lastUsedAt": "string"
                  }
                ],
                "matchedOrigin": "string",
                "latestUsedAt": "string"
              }
            }
          ]
        }
      },
      "fundingAddresses": [
        "string"
      ],
      "transfers": [
        {
          "tokenAddress": "0x...",
          "decimals": 6,
          "tokenSymbol": "USDC",
          "logoUrl": "string",
          "fromAddress": "0x...",
          "toAddress": "0x...",
          "value": "1000000",
          "usdAmount": 1,
          "provenance": {
            "status": "string",
            "outputSystemTags": [
              {
                "type": "string",
                "provider": "string",
                "text": "string",
                "explanationKey": "string",
                "evidence": {
                  "chainId": null,
                  "txHash": "string",
                  "transferOrLogIndex": null,
                  "receiveFromAddress": "string",
                  "poolAddress": "string",
                  "entrypointAddress": "string",
                  "poolTransferOrLogIndex": null
                }
              }
            ],
            "sourceLabelGroupId": "string",
            "olderFundsCount": null,
            "unresolvedReasons": [
              "string"
            ],
            "displayContext": {
              "reason": "string",
              "currentOutputCount": null,
              "sourceCount": null,
              "actionTypes": [
                "string"
              ]
            },
            "funding": {
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ]
            },
            "association": {
              "status": "string",
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ],
              "ignoredUnsolicitedCount": null,
              "summary": {
                "sourceCount": null,
                "userTaggedSourceCount": null,
                "untaggedSourceCount": null,
                "olderFundsCount": null,
                "unknownCount": null
              }
            },
            "display": {
              "badgeKind": "string",
              "label": "string",
              "fundingLabel": "string",
              "associationLabel": "string"
            },
            "editableSource": {
              "id": "string",
              "kind": "string",
              "origin": {
                "chainId": null,
                "txHash": "string",
                "transferOrLogIndex": null
              },
              "address": "string",
              "tagPayloadCiphertext": "string",
              "tagPayloadUpdatedAt": "string",
              "tagEligibility": "string",
              "tagEditable": true,
              "systemTags": [
                {
                  "type": "string",
                  "text": "string",
                  "explanationKey": "string",
                  "evidence": {
                    "address": "string",
                    "origins": [
                      {
                        "origin": "string",
                        "displayName": "string",
                        "iconUrl": "string",
                        "lastUsedAt": "string"
                      }
                    ],
                    "matchedOrigin": "string",
                    "latestUsedAt": "string"
                  }
                }
              ]
            }
          }
        }
      ],
      "swap": {
        "sourceTokenAddress": "0x...",
        "sourceDecimals": 6,
        "sourceTokenSymbol": "USDC",
        "sourceLogoUrl": "string",
        "sourceAmount": "1000000",
        "sourceUsdAmount": 1,
        "destTokenAddress": "0x...",
        "destTokenSymbol": "WETH",
        "destDecimals": 18,
        "destLogoUrl": "string",
        "destAmount": "500000000000000",
        "destUsdAmount": 0.5,
        "outputRecipient": "0x...",
        "outputRecipientIsOwnAddress": true
      },
      "bridge": {
        "sourceTokenAddress": "0x...",
        "sourceDecimals": 6,
        "sourceTokenSymbol": "USDC",
        "sourceLogoUrl": "string",
        "sourceAmount": "1000000",
        "sourceUsdAmount": 1,
        "destTokenAddress": "0x...",
        "destTokenSymbol": "USDC",
        "destDecimals": 6,
        "destLogoUrl": "string",
        "destAmount": "1000000",
        "destUsdAmount": 1,
        "outputRecipient": "0x...",
        "outputRecipientIsOwnAddress": true,
        "bridgeStatus": "pending",
        "destChainId": 8453,
        "destChainName": "Base",
        "destExplorerTxUrlBase": "string",
        "estimatedFillTimeMs": 0,
        "destTxHash": "0x...",
        "refundTxHash": "0x...",
        "refundEligibleAt": "string"
      },
      "pool": {
        "poolAddress": "0x...",
        "tokenAddress": "0x...",
        "decimals": 18,
        "tokenSymbol": "ETH",
        "logoUrl": "string",
        "amount": "1000000000000000",
        "usdAmount": 1,
        "aspStatus": "string",
        "commitmentId": "string",
        "vettingFee": "string",
        "vettingFeeUsd": 0,
        "depositFee": "string",
        "depositFeeUsd": 0
      },
      "dappMeta": {
        "origin": "string",
        "description": "string",
        "iconUrl": "string",
        "connectedAddress": "string",
        "isAccountSetup": true
      },
      "calldata": "string"
    }
  ],
  "pagination": {
    "limit": 100,
    "nextCursor": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Query Parameters
limit
cursor
hideLikelySpam
address
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/activities"

Search activities

POST/v1/accounts/{accountId}/activities/search🔒

Search confirmed account activity directly involving one Ethereum address.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
addressrequiredstring
Ethereum address directly involved in the activity to find.
filtersobject
hideLikelySpamboolean
paginationobject
limitinteger
cursorstring
Base64-encoded cursor for pagination
includeobject
summaryboolean
Responses
200Default Response
Schema
provenanceLabelGroupsrequiredobject
searchSummaryobject
addressrequiredstring
Address directly involved in matching activity.
interactionCountrequirednumber
chainIdsrequirednumber[]
activityrequiredobject[]
txHashrequiredstring | null
quoteIdstring (uuid)
Quote ID that produced this transaction, for correlating pending → confirmed
chainIdrequirednumber
e.g. 8453
chainNamerequiredstring
e.g. "Base"
explorerTxUrlBaserequiredstring | null
Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.
daterequiredstring (date-time)
kindrequired"SEND" | "RECEIVE" | "SELF" | "SWAP" | "BRIDGE" | "CROSS_CHAIN_SWAP" | "POOL_DEPOSIT" | "POOL_RECOVER" | "INCOGNITO_SEND" | "INCOGNITO_SELF_SEND" | "NFT_WITHDRAW" | "DAPP_CALL"
lifecyclerequiredobject | object | object
isExternalrequiredboolean
True for indexed no-intent transactions signed directly by one of the account's addresses.
isLikelySpamrequiredboolean
e.g. false
feesrequiredobject[]
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 18
tokenSymbolrequiredstring
e.g. "ETH"
logoUrlrequiredstring | null
valuerequiredstring
e.g. "1000000000000000"
usdAmountrequirednumber | null
USD value of the fee, or null when token USD pricing is unavailable.
cloakedFeeBpsnumber | null
sourceProvenanceobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
fundingAddressesstring[]
Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.
transfersobject[]
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 6
tokenSymbolrequiredstring
e.g. "USDC"
logoUrlrequiredstring | null
fromAddressrequiredstring
e.g. "0x..."
toAddressrequiredstring
e.g. "0x..."
valuerequiredstring
e.g. "1000000"
usdAmountrequirednumber | null
USD value of the transfer, or null when token USD pricing is unavailable.
provenanceobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
swapobject
sourceTokenAddressrequiredstring
e.g. "0x..."
sourceDecimalsrequirednumber
e.g. 6
sourceTokenSymbolrequiredstring
e.g. "USDC"
sourceLogoUrlrequiredstring | null
sourceAmountrequiredstring
e.g. "1000000"
sourceUsdAmountrequirednumber | null
USD value of the source amount, or null when token USD pricing is unavailable.
destTokenAddressrequiredstring
e.g. "0x..."
destTokenSymbolrequiredstring
e.g. "WETH"
destDecimalsrequirednumber
e.g. 18
destLogoUrlrequiredstring | null
destAmountrequiredstring
e.g. "500000000000000"
destUsdAmountrequirednumber | null
USD value of the destination amount, or null when token USD pricing is unavailable.
outputRecipientrequiredstring
e.g. "0x..."
outputRecipientIsOwnAddressboolean
Whether the output recipient belongs to the Cloaked account that owns this activity.
bridgeobject
sourceTokenAddressrequiredstring
e.g. "0x..."
sourceDecimalsrequirednumber
e.g. 6
sourceTokenSymbolrequiredstring
e.g. "USDC"
sourceLogoUrlrequiredstring | null
sourceAmountrequiredstring
e.g. "1000000"
sourceUsdAmountrequirednumber | null
USD value of the source amount, or null when token USD pricing is unavailable.
destTokenAddressrequiredstring
e.g. "0x..."
destTokenSymbolrequiredstring
e.g. "USDC"
destDecimalsrequirednumber
e.g. 6
destLogoUrlrequiredstring | null
destAmountrequiredstring
e.g. "1000000"
destUsdAmountrequirednumber | null
USD value of the destination amount, or null when token USD pricing is unavailable.
outputRecipientrequiredstring
e.g. "0x..."
outputRecipientIsOwnAddressboolean
Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.
bridgeStatusrequiredstring
e.g. "pending"
destChainIdrequirednumber
e.g. 8453
destChainNamerequiredstring
e.g. "Base"
destExplorerTxUrlBaserequiredstring | null
Explorer tx URL prefix for the destination chain; append destTxHash.
estimatedFillTimeMsrequirednumber | null
destTxHashrequiredstring | null
refundTxHashrequiredstring | null
refundEligibleAtrequiredstring | null
poolobject
poolAddressrequiredstring
e.g. "0x..."
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 18
tokenSymbolrequiredstring
e.g. "ETH"
logoUrlrequiredstring | null
amountrequiredstring
e.g. "1000000000000000"
usdAmountrequirednumber | null
USD value of the pool amount, or null when token USD pricing is unavailable.
aspStatus"pending" | "approved" | "declined" | "failed" | "cancelled"
commitmentIdstring
vettingFeestring
vettingFeeUsdnumber | null
depositFeestring
depositFeeUsdnumber | null
dappMetaobject
originstring
descriptionstring
iconUrlstring
connectedAddressstring
isAccountSetupboolean
calldatastring
Raw calls JSON for dapp-call activities: [{ to, value, data }]
paginationrequiredobject
limitrequirednumber
e.g. 100
nextCursorrequiredstring | null
Base64-encoded cursor for the next confirmed activity page
json
{
  "provenanceLabelGroups": null,
  "searchSummary": {
    "address": "string",
    "interactionCount": 0,
    "chainIds": [
      0
    ]
  },
  "activity": [
    {
      "txHash": "0x...",
      "quoteId": "string",
      "chainId": 8453,
      "chainName": "Base",
      "explorerTxUrlBase": "https://basescan.org/tx/",
      "date": "string",
      "kind": "string",
      "lifecycle": {
        "state": "string"
      },
      "isExternal": false,
      "isLikelySpam": false,
      "fees": [
        {
          "tokenAddress": "0x...",
          "decimals": 18,
          "tokenSymbol": "ETH",
          "logoUrl": "string",
          "value": "1000000000000000",
          "usdAmount": 0.001
        }
      ],
      "cloakedFeeBps": 0,
      "sourceProvenance": {
        "status": "string",
        "outputSystemTags": [
          {
            "type": "string",
            "provider": "string",
            "text": "string",
            "explanationKey": "string",
            "evidence": {
              "chainId": null,
              "txHash": "string",
              "transferOrLogIndex": null,
              "receiveFromAddress": "string",
              "poolAddress": "string",
              "entrypointAddress": "string",
              "poolTransferOrLogIndex": null
            }
          }
        ],
        "sourceLabelGroupId": "string",
        "olderFundsCount": null,
        "unresolvedReasons": [
          "string"
        ],
        "displayContext": {
          "reason": "string",
          "currentOutputCount": null,
          "sourceCount": null,
          "actionTypes": [
            "string"
          ]
        },
        "funding": {
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ]
        },
        "association": {
          "status": "string",
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ],
          "ignoredUnsolicitedCount": null,
          "summary": {
            "sourceCount": null,
            "userTaggedSourceCount": null,
            "untaggedSourceCount": null,
            "olderFundsCount": null,
            "unknownCount": null
          }
        },
        "display": {
          "badgeKind": "string",
          "label": "string",
          "fundingLabel": "string",
          "associationLabel": "string"
        },
        "editableSource": {
          "id": "string",
          "kind": "string",
          "origin": {
            "chainId": null,
            "txHash": "string",
            "transferOrLogIndex": null
          },
          "address": "string",
          "tagPayloadCiphertext": "string",
          "tagPayloadUpdatedAt": "string",
          "tagEligibility": "string",
          "tagEditable": true,
          "systemTags": [
            {
              "type": "string",
              "text": "string",
              "explanationKey": "string",
              "evidence": {
                "address": "string",
                "origins": [
                  {
                    "origin": "string",
                    "displayName": "string",
                    "iconUrl": "string",
                    "lastUsedAt": "string"
                  }
                ],
                "matchedOrigin": "string",
                "latestUsedAt": "string"
              }
            }
          ]
        }
      },
      "fundingAddresses": [
        "string"
      ],
      "transfers": [
        {
          "tokenAddress": "0x...",
          "decimals": 6,
          "tokenSymbol": "USDC",
          "logoUrl": "string",
          "fromAddress": "0x...",
          "toAddress": "0x...",
          "value": "1000000",
          "usdAmount": 1,
          "provenance": {
            "status": "string",
            "outputSystemTags": [
              {
                "type": "string",
                "provider": "string",
                "text": "string",
                "explanationKey": "string",
                "evidence": {
                  "chainId": null,
                  "txHash": "string",
                  "transferOrLogIndex": null,
                  "receiveFromAddress": "string",
                  "poolAddress": "string",
                  "entrypointAddress": "string",
                  "poolTransferOrLogIndex": null
                }
              }
            ],
            "sourceLabelGroupId": "string",
            "olderFundsCount": null,
            "unresolvedReasons": [
              "string"
            ],
            "displayContext": {
              "reason": "string",
              "currentOutputCount": null,
              "sourceCount": null,
              "actionTypes": [
                "string"
              ]
            },
            "funding": {
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ]
            },
            "association": {
              "status": "string",
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ],
              "ignoredUnsolicitedCount": null,
              "summary": {
                "sourceCount": null,
                "userTaggedSourceCount": null,
                "untaggedSourceCount": null,
                "olderFundsCount": null,
                "unknownCount": null
              }
            },
            "display": {
              "badgeKind": "string",
              "label": "string",
              "fundingLabel": "string",
              "associationLabel": "string"
            },
            "editableSource": {
              "id": "string",
              "kind": "string",
              "origin": {
                "chainId": null,
                "txHash": "string",
                "transferOrLogIndex": null
              },
              "address": "string",
              "tagPayloadCiphertext": "string",
              "tagPayloadUpdatedAt": "string",
              "tagEligibility": "string",
              "tagEditable": true,
              "systemTags": [
                {
                  "type": "string",
                  "text": "string",
                  "explanationKey": "string",
                  "evidence": {
                    "address": "string",
                    "origins": [
                      {
                        "origin": "string",
                        "displayName": "string",
                        "iconUrl": "string",
                        "lastUsedAt": "string"
                      }
                    ],
                    "matchedOrigin": "string",
                    "latestUsedAt": "string"
                  }
                }
              ]
            }
          }
        }
      ],
      "swap": {
        "sourceTokenAddress": "0x...",
        "sourceDecimals": 6,
        "sourceTokenSymbol": "USDC",
        "sourceLogoUrl": "string",
        "sourceAmount": "1000000",
        "sourceUsdAmount": 1,
        "destTokenAddress": "0x...",
        "destTokenSymbol": "WETH",
        "destDecimals": 18,
        "destLogoUrl": "string",
        "destAmount": "500000000000000",
        "destUsdAmount": 0.5,
        "outputRecipient": "0x...",
        "outputRecipientIsOwnAddress": true
      },
      "bridge": {
        "sourceTokenAddress": "0x...",
        "sourceDecimals": 6,
        "sourceTokenSymbol": "USDC",
        "sourceLogoUrl": "string",
        "sourceAmount": "1000000",
        "sourceUsdAmount": 1,
        "destTokenAddress": "0x...",
        "destTokenSymbol": "USDC",
        "destDecimals": 6,
        "destLogoUrl": "string",
        "destAmount": "1000000",
        "destUsdAmount": 1,
        "outputRecipient": "0x...",
        "outputRecipientIsOwnAddress": true,
        "bridgeStatus": "pending",
        "destChainId": 8453,
        "destChainName": "Base",
        "destExplorerTxUrlBase": "string",
        "estimatedFillTimeMs": 0,
        "destTxHash": "0x...",
        "refundTxHash": "0x...",
        "refundEligibleAt": "string"
      },
      "pool": {
        "poolAddress": "0x...",
        "tokenAddress": "0x...",
        "decimals": 18,
        "tokenSymbol": "ETH",
        "logoUrl": "string",
        "amount": "1000000000000000",
        "usdAmount": 1,
        "aspStatus": "string",
        "commitmentId": "string",
        "vettingFee": "string",
        "vettingFeeUsd": 0,
        "depositFee": "string",
        "depositFeeUsd": 0
      },
      "dappMeta": {
        "origin": "string",
        "description": "string",
        "iconUrl": "string",
        "connectedAddress": "string",
        "isAccountSetup": true
      },
      "calldata": "string"
    }
  ],
  "pagination": {
    "limit": 100,
    "nextCursor": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "address": "",
  "filters": {
    "hideLikelySpam": true
  },
  "pagination": {
    "limit": null,
    "cursor": ""
  },
  "include": {
    "summary": true
  }
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/activities/search"

Get pending activity statuses

POST/v1/accounts/{accountId}/activities/pending/status🔒

Return the current lifecycle projection for known pending activity quote IDs. Missing or no-longer-pending IDs are omitted.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
quoteIdsrequiredstring[]
Responses
200Default Response
Schema
statusesrequiredobject[]
quoteIdrequiredstring (uuid)
txHashrequiredstring | null
lifecyclerequiredobject | object
updatedAtrequiredstring (date-time)
json
{
  "statuses": [
    {
      "quoteId": "string",
      "txHash": "string",
      "lifecycle": {
        "state": "string",
        "relayStatus": "string"
      },
      "updatedAt": "string"
    }
  ]
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "quoteIds": [
    ""
  ]
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/activities/pending/status"

Get pending activities

GET/v1/accounts/{accountId}/activities/pending🔒

List in-flight relay transactions (queued, pending, stuck) and recently confirmed/failed transactions for the account. The response uses the same shape as GET /activities: same kind values, same payload sub-objects. The lifecycle.state discriminates between 'in_flight', 'indexed', and 'failed'. Recently confirmed transactions are included for up to 5 minutes so the client can show continuous state while the transaction is indexed.

Parameters
NameInTypeDescription
addressquerystringOwned address to scope pending activity to.
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
provenanceLabelGroupsrequiredobject
pendingrequiredobject[]
txHashrequiredstring | null
quoteIdstring (uuid)
Quote ID that produced this transaction, for correlating pending → confirmed
chainIdrequirednumber
e.g. 8453
chainNamerequiredstring
e.g. "Base"
explorerTxUrlBaserequiredstring | null
Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.
daterequiredstring (date-time)
kindrequired"SEND" | "RECEIVE" | "SELF" | "SWAP" | "BRIDGE" | "CROSS_CHAIN_SWAP" | "POOL_DEPOSIT" | "POOL_RECOVER" | "INCOGNITO_SEND" | "INCOGNITO_SELF_SEND" | "NFT_WITHDRAW" | "DAPP_CALL"
lifecyclerequiredobject | object | object
isExternalrequiredboolean
True for indexed no-intent transactions signed directly by one of the account's addresses.
isLikelySpamrequiredboolean
e.g. false
feesrequiredobject[]
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 18
tokenSymbolrequiredstring
e.g. "ETH"
logoUrlrequiredstring | null
valuerequiredstring
e.g. "1000000000000000"
usdAmountrequirednumber | null
USD value of the fee, or null when token USD pricing is unavailable.
cloakedFeeBpsnumber | null
sourceProvenanceobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
fundingAddressesstring[]
Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.
transfersobject[]
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 6
tokenSymbolrequiredstring
e.g. "USDC"
logoUrlrequiredstring | null
fromAddressrequiredstring
e.g. "0x..."
toAddressrequiredstring
e.g. "0x..."
valuerequiredstring
e.g. "1000000"
usdAmountrequirednumber | null
USD value of the transfer, or null when token USD pricing is unavailable.
provenanceobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
swapobject
sourceTokenAddressrequiredstring
e.g. "0x..."
sourceDecimalsrequirednumber
e.g. 6
sourceTokenSymbolrequiredstring
e.g. "USDC"
sourceLogoUrlrequiredstring | null
sourceAmountrequiredstring
e.g. "1000000"
sourceUsdAmountrequirednumber | null
USD value of the source amount, or null when token USD pricing is unavailable.
destTokenAddressrequiredstring
e.g. "0x..."
destTokenSymbolrequiredstring
e.g. "WETH"
destDecimalsrequirednumber
e.g. 18
destLogoUrlrequiredstring | null
destAmountrequiredstring
e.g. "500000000000000"
destUsdAmountrequirednumber | null
USD value of the destination amount, or null when token USD pricing is unavailable.
outputRecipientrequiredstring
e.g. "0x..."
outputRecipientIsOwnAddressboolean
Whether the output recipient belongs to the Cloaked account that owns this activity.
bridgeobject
sourceTokenAddressrequiredstring
e.g. "0x..."
sourceDecimalsrequirednumber
e.g. 6
sourceTokenSymbolrequiredstring
e.g. "USDC"
sourceLogoUrlrequiredstring | null
sourceAmountrequiredstring
e.g. "1000000"
sourceUsdAmountrequirednumber | null
USD value of the source amount, or null when token USD pricing is unavailable.
destTokenAddressrequiredstring
e.g. "0x..."
destTokenSymbolrequiredstring
e.g. "USDC"
destDecimalsrequirednumber
e.g. 6
destLogoUrlrequiredstring | null
destAmountrequiredstring
e.g. "1000000"
destUsdAmountrequirednumber | null
USD value of the destination amount, or null when token USD pricing is unavailable.
outputRecipientrequiredstring
e.g. "0x..."
outputRecipientIsOwnAddressboolean
Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.
bridgeStatusrequiredstring
e.g. "pending"
destChainIdrequirednumber
e.g. 8453
destChainNamerequiredstring
e.g. "Base"
destExplorerTxUrlBaserequiredstring | null
Explorer tx URL prefix for the destination chain; append destTxHash.
estimatedFillTimeMsrequirednumber | null
destTxHashrequiredstring | null
refundTxHashrequiredstring | null
refundEligibleAtrequiredstring | null
poolobject
poolAddressrequiredstring
e.g. "0x..."
tokenAddressrequiredstring
e.g. "0x..."
decimalsrequirednumber
e.g. 18
tokenSymbolrequiredstring
e.g. "ETH"
logoUrlrequiredstring | null
amountrequiredstring
e.g. "1000000000000000"
usdAmountrequirednumber | null
USD value of the pool amount, or null when token USD pricing is unavailable.
aspStatus"pending" | "approved" | "declined" | "failed" | "cancelled"
commitmentIdstring
vettingFeestring
vettingFeeUsdnumber | null
depositFeestring
depositFeeUsdnumber | null
dappMetaobject
originstring
descriptionstring
iconUrlstring
connectedAddressstring
isAccountSetupboolean
calldatastring
Raw calls JSON for dapp-call activities: [{ to, value, data }]
json
{
  "provenanceLabelGroups": null,
  "pending": [
    {
      "txHash": "0x...",
      "quoteId": "string",
      "chainId": 8453,
      "chainName": "Base",
      "explorerTxUrlBase": "https://basescan.org/tx/",
      "date": "string",
      "kind": "string",
      "lifecycle": {
        "state": "string"
      },
      "isExternal": false,
      "isLikelySpam": false,
      "fees": [
        {
          "tokenAddress": "0x...",
          "decimals": 18,
          "tokenSymbol": "ETH",
          "logoUrl": "string",
          "value": "1000000000000000",
          "usdAmount": 0.001
        }
      ],
      "cloakedFeeBps": 0,
      "sourceProvenance": {
        "status": "string",
        "outputSystemTags": [
          {
            "type": "string",
            "provider": "string",
            "text": "string",
            "explanationKey": "string",
            "evidence": {
              "chainId": null,
              "txHash": "string",
              "transferOrLogIndex": null,
              "receiveFromAddress": "string",
              "poolAddress": "string",
              "entrypointAddress": "string",
              "poolTransferOrLogIndex": null
            }
          }
        ],
        "sourceLabelGroupId": "string",
        "olderFundsCount": null,
        "unresolvedReasons": [
          "string"
        ],
        "displayContext": {
          "reason": "string",
          "currentOutputCount": null,
          "sourceCount": null,
          "actionTypes": [
            "string"
          ]
        },
        "funding": {
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ]
        },
        "association": {
          "status": "string",
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ],
          "ignoredUnsolicitedCount": null,
          "summary": {
            "sourceCount": null,
            "userTaggedSourceCount": null,
            "untaggedSourceCount": null,
            "olderFundsCount": null,
            "unknownCount": null
          }
        },
        "display": {
          "badgeKind": "string",
          "label": "string",
          "fundingLabel": "string",
          "associationLabel": "string"
        },
        "editableSource": {
          "id": "string",
          "kind": "string",
          "origin": {
            "chainId": null,
            "txHash": "string",
            "transferOrLogIndex": null
          },
          "address": "string",
          "tagPayloadCiphertext": "string",
          "tagPayloadUpdatedAt": "string",
          "tagEligibility": "string",
          "tagEditable": true,
          "systemTags": [
            {
              "type": "string",
              "text": "string",
              "explanationKey": "string",
              "evidence": {
                "address": "string",
                "origins": [
                  {
                    "origin": "string",
                    "displayName": "string",
                    "iconUrl": "string",
                    "lastUsedAt": "string"
                  }
                ],
                "matchedOrigin": "string",
                "latestUsedAt": "string"
              }
            }
          ]
        }
      },
      "fundingAddresses": [
        "string"
      ],
      "transfers": [
        {
          "tokenAddress": "0x...",
          "decimals": 6,
          "tokenSymbol": "USDC",
          "logoUrl": "string",
          "fromAddress": "0x...",
          "toAddress": "0x...",
          "value": "1000000",
          "usdAmount": 1,
          "provenance": {
            "status": "string",
            "outputSystemTags": [
              {
                "type": "string",
                "provider": "string",
                "text": "string",
                "explanationKey": "string",
                "evidence": {
                  "chainId": null,
                  "txHash": "string",
                  "transferOrLogIndex": null,
                  "receiveFromAddress": "string",
                  "poolAddress": "string",
                  "entrypointAddress": "string",
                  "poolTransferOrLogIndex": null
                }
              }
            ],
            "sourceLabelGroupId": "string",
            "olderFundsCount": null,
            "unresolvedReasons": [
              "string"
            ],
            "displayContext": {
              "reason": "string",
              "currentOutputCount": null,
              "sourceCount": null,
              "actionTypes": [
                "string"
              ]
            },
            "funding": {
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ]
            },
            "association": {
              "status": "string",
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ],
              "ignoredUnsolicitedCount": null,
              "summary": {
                "sourceCount": null,
                "userTaggedSourceCount": null,
                "untaggedSourceCount": null,
                "olderFundsCount": null,
                "unknownCount": null
              }
            },
            "display": {
              "badgeKind": "string",
              "label": "string",
              "fundingLabel": "string",
              "associationLabel": "string"
            },
            "editableSource": {
              "id": "string",
              "kind": "string",
              "origin": {
                "chainId": null,
                "txHash": "string",
                "transferOrLogIndex": null
              },
              "address": "string",
              "tagPayloadCiphertext": "string",
              "tagPayloadUpdatedAt": "string",
              "tagEligibility": "string",
              "tagEditable": true,
              "systemTags": [
                {
                  "type": "string",
                  "text": "string",
                  "explanationKey": "string",
                  "evidence": {
                    "address": "string",
                    "origins": [
                      {
                        "origin": "string",
                        "displayName": "string",
                        "iconUrl": "string",
                        "lastUsedAt": "string"
                      }
                    ],
                    "matchedOrigin": "string",
                    "latestUsedAt": "string"
                  }
                }
              ]
            }
          }
        }
      ],
      "swap": {
        "sourceTokenAddress": "0x...",
        "sourceDecimals": 6,
        "sourceTokenSymbol": "USDC",
        "sourceLogoUrl": "string",
        "sourceAmount": "1000000",
        "sourceUsdAmount": 1,
        "destTokenAddress": "0x...",
        "destTokenSymbol": "WETH",
        "destDecimals": 18,
        "destLogoUrl": "string",
        "destAmount": "500000000000000",
        "destUsdAmount": 0.5,
        "outputRecipient": "0x...",
        "outputRecipientIsOwnAddress": true
      },
      "bridge": {
        "sourceTokenAddress": "0x...",
        "sourceDecimals": 6,
        "sourceTokenSymbol": "USDC",
        "sourceLogoUrl": "string",
        "sourceAmount": "1000000",
        "sourceUsdAmount": 1,
        "destTokenAddress": "0x...",
        "destTokenSymbol": "USDC",
        "destDecimals": 6,
        "destLogoUrl": "string",
        "destAmount": "1000000",
        "destUsdAmount": 1,
        "outputRecipient": "0x...",
        "outputRecipientIsOwnAddress": true,
        "bridgeStatus": "pending",
        "destChainId": 8453,
        "destChainName": "Base",
        "destExplorerTxUrlBase": "string",
        "estimatedFillTimeMs": 0,
        "destTxHash": "0x...",
        "refundTxHash": "0x...",
        "refundEligibleAt": "string"
      },
      "pool": {
        "poolAddress": "0x...",
        "tokenAddress": "0x...",
        "decimals": 18,
        "tokenSymbol": "ETH",
        "logoUrl": "string",
        "amount": "1000000000000000",
        "usdAmount": 1,
        "aspStatus": "string",
        "commitmentId": "string",
        "vettingFee": "string",
        "vettingFeeUsd": 0,
        "depositFee": "string",
        "depositFeeUsd": 0
      },
      "dappMeta": {
        "origin": "string",
        "description": "string",
        "iconUrl": "string",
        "connectedAddress": "string",
        "isAccountSetup": true
      },
      "calldata": "string"
    }
  ]
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Query Parameters
address
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/activities/pending"

List activity notes

GET/v1/accounts/{accountId}/activity-notes🔒

List client-encrypted private notes attached to account activity.

Parameters
NameInTypeDescription
limitqueryinteger—
cursorquerystring—
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
notesrequiredobject[]
referencerequiredobject | object
notePayloadCiphertextrequiredstring
Client-encrypted private activity note payload.
notePayloadUpdatedAtrequiredstring (date-time)
paginationrequiredobject
limitrequiredinteger
nextCursorrequiredstring | null
json
{
  "notes": [
    {
      "reference": {
        "type": "string",
        "quoteId": "string"
      },
      "notePayloadCiphertext": "string",
      "notePayloadUpdatedAt": "string"
    }
  ],
  "pagination": {
    "limit": null,
    "nextCursor": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
Query Parameters
limit
cursor
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/activity-notes"

Set activity note

PUT/v1/accounts/{accountId}/activity-notes🔒

Set or clear a client-encrypted private note on one account activity.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
referencerequiredobject | object
notePayloadCiphertextrequiredstring | null
Responses
200Default Response
Schema
noterequiredobject | null
json
{
  "note": {
    "reference": {
      "type": "string",
      "quoteId": "string"
    },
    "notePayloadCiphertext": "string",
    "notePayloadUpdatedAt": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
Request Body
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
  "reference": {
    "type": "",
    "quoteId": ""
  },
  "notePayloadCiphertext": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/activity-notes"

Get deposit review summary

GET/v1/accounts/{accountId}/deposit-review/summary🔒

Return deposit review counts and address markers for the account.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
needsReviewCountrequiredinteger
unseenNeedsReviewrequiredinteger
markersrequiredobject[]
addressrequiredstring
json
{
  "needsReviewCount": null,
  "unseenNeedsReview": null,
  "markers": [
    {
      "address": "string"
    }
  ]
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/deposit-review/summary"

Get deposit review

GET/v1/accounts/{accountId}/deposit-review🔒

Return one review row per fresh inbound address, including current review state, visible assets, tags, and Incognito deposit progress.

Parameters
NameInTypeDescription
tabqueryany—
cursorquerystring—
limitqueryinteger—
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
itemsrequiredobject[]
idrequiredstring
addressrequiredstring
reviewStatusrequired"needs_review" | "in_progress" | "done"
statusReasonrequired"untagged" | "tags_added" | "pool_deposit_in_progress" | "pool_deposit_rejected" | "pool_deposited"
provenanceSourcesrequiredobject[]
idrequiredstring
Stable provenance source key
kindrequired"receive"
originrequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
addressrequiredstring
Owned address where this receive source originally landed
tagPayloadCiphertextrequiredstring | null
tagPayloadUpdatedAtrequiredstring | null
tagEligibilityrequired"eligible" | "received_before_tagging"
tagEditablerequiredboolean
True when this source is a traceable external receive that may be tagged by the current account
systemTagsrequiredarray
Server-derived tags that follow this funding lineage
assetsrequiredobject[]
idrequiredstring
addressrequiredstring
reviewStatusrequired"needs_review" | "in_progress" | "done"
statusReasonrequired"untagged" | "tags_added" | "pool_deposit_in_progress" | "pool_deposit_rejected" | "pool_deposited"
chainIdrequiredinteger
chainNamerequiredstring
tokenAddressrequiredstring
tokenSymbolrequiredstring
decimalsrequiredinteger
logoUrlrequiredstring | null
amountrequiredstring
Displayed amount in smallest unit
availablerequiredstring
Currently available visible amount in smallest unit
pendingrequiredstring
Currently pending visible amount in smallest unit
receiveCountrequiredinteger
rawReceiveCountrequiredinteger
trustedReceiveActionCountrequiredinteger
trustedReceiveActionTypesrequiredstring[]
lastReceivedAtrequiredstring | null
receiveTxHashrequiredstring | null
usdAmountrequirednumber | null
pricePerTokenrequirednumber | null
poolMinDepositrequiredstring | null
canConvertrequiredboolean
convertUnavailableReasonrequiredstring | null
poolDepositrequiredobject | null
primaryAssetrequiredobject
idrequiredstring
addressrequiredstring
reviewStatusrequired"needs_review" | "in_progress" | "done"
statusReasonrequired"untagged" | "tags_added" | "pool_deposit_in_progress" | "pool_deposit_rejected" | "pool_deposited"
chainIdrequiredinteger
chainNamerequiredstring
tokenAddressrequiredstring
tokenSymbolrequiredstring
decimalsrequiredinteger
logoUrlrequiredstring | null
amountrequiredstring
Displayed amount in smallest unit
availablerequiredstring
Currently available visible amount in smallest unit
pendingrequiredstring
Currently pending visible amount in smallest unit
receiveCountrequiredinteger
rawReceiveCountrequiredinteger
trustedReceiveActionCountrequiredinteger
trustedReceiveActionTypesrequiredstring[]
lastReceivedAtrequiredstring | null
receiveTxHashrequiredstring | null
usdAmountrequirednumber | null
pricePerTokenrequirednumber | null
poolMinDepositrequiredstring | null
canConvertrequiredboolean
convertUnavailableReasonrequiredstring | null
poolDepositrequiredobject | null
receiveCountrequiredinteger
rawReceiveCountrequiredinteger
trustedReceiveActionCountrequiredinteger
trustedReceiveActionTypesrequiredstring[]
assetCountrequiredinteger
chainCountrequiredinteger
lastReceivedAtrequiredstring | null
usdAmountrequirednumber | null
canConvertrequiredboolean
countsrequiredobject
needsReviewrequiredinteger
inProgressrequiredinteger
donerequiredinteger
pageInforequiredobject
nextCursorrequiredstring | null
hasMorerequiredboolean
limitrequiredinteger
unseenNeedsReviewrequiredinteger
needs-review addresses received after the account last opened Review. Drives the notification badge; 0 once everything current has been seen.
json
{
  "items": [
    {
      "id": "string",
      "address": "string",
      "reviewStatus": "string",
      "statusReason": "string",
      "provenanceSources": [
        {
          "id": "string",
          "kind": "string",
          "origin": {
            "chainId": null,
            "txHash": "string",
            "transferOrLogIndex": null
          },
          "address": "string",
          "tagPayloadCiphertext": "string",
          "tagPayloadUpdatedAt": "string",
          "tagEligibility": "string",
          "tagEditable": true,
          "systemTags": [
            {
              "type": "string",
              "text": "string",
              "explanationKey": "string",
              "evidence": {
                "address": "string",
                "origins": [
                  {
                    "origin": "string",
                    "displayName": "string",
                    "iconUrl": "string",
                    "lastUsedAt": "string"
                  }
                ],
                "matchedOrigin": "string",
                "latestUsedAt": "string"
              }
            }
          ]
        }
      ],
      "assets": [
        {
          "id": "string",
          "address": "string",
          "reviewStatus": "string",
          "statusReason": "string",
          "chainId": null,
          "chainName": "string",
          "tokenAddress": "string",
          "tokenSymbol": "string",
          "decimals": null,
          "logoUrl": "string",
          "amount": "string",
          "available": "string",
          "pending": "string",
          "receiveCount": null,
          "rawReceiveCount": null,
          "trustedReceiveActionCount": null,
          "trustedReceiveActionTypes": [
            "string"
          ],
          "lastReceivedAt": "string",
          "receiveTxHash": "string",
          "usdAmount": 0,
          "pricePerToken": 0,
          "poolMinDeposit": "string",
          "canConvert": true,
          "convertUnavailableReason": "string",
          "poolDeposit": {
            "commitmentId": "string",
            "status": "string",
            "txHash": "string",
            "amount": "string",
            "updatedAt": "string"
          }
        }
      ],
      "primaryAsset": {
        "id": "string",
        "address": "string",
        "reviewStatus": "string",
        "statusReason": "string",
        "chainId": null,
        "chainName": "string",
        "tokenAddress": "string",
        "tokenSymbol": "string",
        "decimals": null,
        "logoUrl": "string",
        "amount": "string",
        "available": "string",
        "pending": "string",
        "receiveCount": null,
        "rawReceiveCount": null,
        "trustedReceiveActionCount": null,
        "trustedReceiveActionTypes": [
          "string"
        ],
        "lastReceivedAt": "string",
        "receiveTxHash": "string",
        "usdAmount": 0,
        "pricePerToken": 0,
        "poolMinDeposit": "string",
        "canConvert": true,
        "convertUnavailableReason": "string",
        "poolDeposit": {
          "commitmentId": "string",
          "status": "string",
          "txHash": "string",
          "amount": "string",
          "updatedAt": "string"
        }
      },
      "receiveCount": null,
      "rawReceiveCount": null,
      "trustedReceiveActionCount": null,
      "trustedReceiveActionTypes": [
        "string"
      ],
      "assetCount": null,
      "chainCount": null,
      "lastReceivedAt": "string",
      "usdAmount": 0,
      "canConvert": true
    }
  ],
  "counts": {
    "needsReview": null,
    "inProgress": null,
    "done": null
  },
  "pageInfo": {
    "nextCursor": "string",
    "hasMore": true,
    "limit": null
  },
  "unseenNeedsReview": null
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Query Parameters
tab
cursor
limit
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/deposit-review"

Mark deposit review seen

POST/v1/accounts/{accountId}/deposit-review/seen🔒

Mark the account's deposit-review notifications as seen, clearing the Review badge. Idempotent; the marker only moves forward.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
seenAtrequiredstring (date-time)
The persisted "seen" marker after this request.
json
{
  "seenAt": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X POST \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/deposit-review/seen"

Transact

Sending, swapping, bridging, converting to incognito, and cashing out all follow the same flow: get a quote, then submit.

Get quote signer public key

GET/v1/.well-known/quote-signer-public-key

Retrieve the server's P-256 ECDSA public key so clients can verify that quote responses were authentically signed by the server and haven't been tampered with.

Responses
200Default Response
Schema
publicKeyrequiredstring
e.g. "04..."
formatrequiredstring
e.g. "hex"
curverequiredstring
e.g. "P-256"
algorithmrequiredstring
e.g. "ECDSA"
json
{
  "publicKey": "04...",
  "format": "hex",
  "curve": "P-256",
  "algorithm": "ECDSA"
}
Try it
curl -X GET \
  "https://api-stg.clkd.xyz/v1/.well-known/quote-signer-public-key"

List supported pools

GET/v1/supported-pools🔒

List privacy pools available to the authenticated user, including pool contract addresses, accepted tokens, deposit limits, and ASP (Association Set Provider) details. Feature-flagged pools are only included when the flag is enabled for the account.

Responses
200Default Response
Schema
any[]
json
[
  {
    "provider": "string",
    "poolAddress": "0x...",
    "chainId": 1,
    "chainName": "Ethereum",
    "token": "0x...",
    "tokenSymbol": "ETH",
    "decimals": 18,
    "logoUrl": "https://...",
    "minDeposit": "10000000000000000",
    "maxDeposit": "100000000000000000000",
    "totalBalance": "2659000000000000000000",
    "scope": "12345678901234567890",
    "asp": {
      "name": "0xbow",
      "policyUrl": "https://0xbow.io/policy"
    },
    "maxRelayFeeBPS": 1000,
    "withdrawalFeePerProofWei": "95000000000000"
  }
]
Try it
curl -X GET \
  "https://api-stg.clkd.xyz/v1/supported-pools"

List provenance address tags

GET/v1/accounts/{accountId}/provenance-address-tags🔒

List encrypted display tag payload ciphertexts for owned addresses.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
tagsrequiredobject[]
addressrequiredstring
tagPayloadCiphertextrequiredstring
tagPayloadUpdatedAtrequiredstring (date-time)
json
{
  "tags": [
    {
      "address": "string",
      "tagPayloadCiphertext": "string",
      "tagPayloadUpdatedAt": "string"
    }
  ]
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/provenance-address-tags"

Set provenance address tags

PUT/v1/accounts/{accountId}/provenance-address-tags/{address}🔒

Set or clear encrypted display tag payload ciphertext for an owned address.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
address*pathstringOwned address whose private tags should be updated
Request Body
tagPayloadCiphertextrequiredstring | null
Responses
200Default Response
Schema
tagrequiredobject
addressrequiredstring
tagPayloadCiphertextrequiredstring | null
tagPayloadUpdatedAtrequiredstring | null
json
{
  "tag": {
    "address": "string",
    "tagPayloadCiphertext": "string",
    "tagPayloadUpdatedAt": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
address
Request Body
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
  "tagPayloadCiphertext": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/provenance-address-tags/{address}"

Get address balances

GET/v1/accounts/{accountId}/address-balances🔒

List address-held balances grouped by address, enriched with token metadata, dApp usage, receive history, and provenance metadata.

Parameters
NameInTypeDescription
purposequerystringSelect addresses with unlocked funds that may fund a transaction, excluding addresses reserved for active Cloakie deposits. Use available for the fundable amount; amount, usdAmount, and totalUsdBalance continue to include locked funds. Requires chainId and token.
addressquerystringReturn balances for this exact owned address only
chainIdquerynumberFilter balances to one chain ID
tokenquerystringFilter balances to one token address
dappOriginquerystringFilter recently-used addresses by this dApp origin
limitquerynumberMax addresses to return. Omit to return all.
offsetquerynumber—
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
provenanceLabelGroupsrequiredobject
dapprequiredobject | null
addressesrequiredobject[]
addressrequiredstring
noncerequiredstring
usedOriginsrequiredstring[]
usedAppsrequiredobject[]
originrequiredstring
displayNamerequiredstring
iconUrlrequiredstring | null
recentlyUsedByDapprequiredboolean
totalUsdBalancerequirednumber | null
USD value of all returned balances, including unlocked and locked outputs
balancesrequiredobject[]
chainIdrequirednumber
chainNamerequiredstring
tokenrequiredstring
tokenSymbolrequiredstring
decimalsrequirednumber
logoUrlrequiredstring | null
amountrequiredstring
Total raw amount in smallest unit, including unlocked and locked outputs
availablerequiredstring
Currently unlocked raw amount in smallest unit
pendingrequiredstring
Currently locked raw amount in smallest unit
usdAmountrequirednumber | null
USD value of the total amount, including unlocked and locked outputs
pricePerTokenrequirednumber | null
priceStalerequiredboolean
listedrequiredboolean
Whether the token is visible in the account token catalog
idCountrequirednumber
Number of output IDs represented by this balance; funding mode counts only unlocked outputs
addressSummaryrequiredobject
receiveCountrequirednumber
Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.
rawReceiveCountrequirednumber
Literal distinct inbound transfer/log count before trusted-action collapsing.
trustedReceiveActionCountrequirednumber
Number of Cloaked-managed receive actions collapsed into receiveCount.
trustedReceiveActionTypesrequiredstring[]
assetCountrequirednumber
Distinct priced/displayable chain-token assets seen for this address
chainCountrequirednumber
Distinct networks with priced/displayable assets at this address
assetsrequiredobject[]
chainIdrequirednumber
chainNamerequiredstring
tokenrequiredstring
tokenSymbolrequiredstring
decimalsrequirednumber
logoUrlrequiredstring | null
amountrequiredstring
Total raw amount in smallest unit, including unlocked and locked outputs
usdAmountrequirednumber | null
USD value of the total amount, including unlocked and locked outputs
pricePerTokenrequirednumber | null
provenancerequiredobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
lastReceivedAtrequiredstring | null
Most recent included output. In funding mode this considers only unlocked outputs.
totalrequirednumber
Total number of matching addresses before pagination
json
{
  "provenanceLabelGroups": null,
  "dapp": {
    "origin": "string",
    "displayName": "string",
    "iconUrl": "string",
    "recognitionStatus": "string",
    "verified": true
  },
  "addresses": [
    {
      "address": "string",
      "nonce": "string",
      "usedOrigins": [
        "string"
      ],
      "usedApps": [
        {
          "origin": "string",
          "displayName": "string",
          "iconUrl": "string"
        }
      ],
      "recentlyUsedByDapp": true,
      "totalUsdBalance": 0,
      "balances": [
        {
          "chainId": 0,
          "chainName": "string",
          "token": "string",
          "tokenSymbol": "string",
          "decimals": 0,
          "logoUrl": "string",
          "amount": "string",
          "available": "string",
          "pending": "string",
          "usdAmount": 0,
          "pricePerToken": 0,
          "priceStale": true,
          "listed": true,
          "idCount": 0,
          "addressSummary": {
            "receiveCount": 0,
            "rawReceiveCount": 0,
            "trustedReceiveActionCount": 0,
            "trustedReceiveActionTypes": [
              "string"
            ],
            "assetCount": 0,
            "chainCount": 0,
            "assets": [
              {
                "chainId": 0,
                "chainName": "string",
                "token": "string",
                "tokenSymbol": "string",
                "decimals": 0,
                "logoUrl": "string",
                "amount": "string",
                "usdAmount": 0,
                "pricePerToken": 0
              }
            ]
          },
          "provenance": {
            "status": "string",
            "outputSystemTags": [
              {
                "type": "string",
                "provider": "string",
                "text": "string",
                "explanationKey": "string",
                "evidence": {
                  "chainId": null,
                  "txHash": "string",
                  "transferOrLogIndex": null,
                  "receiveFromAddress": "string",
                  "poolAddress": "string",
                  "entrypointAddress": "string",
                  "poolTransferOrLogIndex": null
                }
              }
            ],
            "sourceLabelGroupId": "string",
            "olderFundsCount": null,
            "unresolvedReasons": [
              "string"
            ],
            "displayContext": {
              "reason": "string",
              "currentOutputCount": null,
              "sourceCount": null,
              "actionTypes": [
                "string"
              ]
            },
            "funding": {
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ]
            },
            "association": {
              "status": "string",
              "labelGroupId": "string",
              "olderFundsCount": null,
              "unresolvedReasons": [
                "string"
              ],
              "ignoredUnsolicitedCount": null,
              "summary": {
                "sourceCount": null,
                "userTaggedSourceCount": null,
                "untaggedSourceCount": null,
                "olderFundsCount": null,
                "unknownCount": null
              }
            },
            "display": {
              "badgeKind": "string",
              "label": "string",
              "fundingLabel": "string",
              "associationLabel": "string"
            },
            "editableSource": {
              "id": "string",
              "kind": "string",
              "origin": {
                "chainId": null,
                "txHash": "string",
                "transferOrLogIndex": null
              },
              "address": "string",
              "tagPayloadCiphertext": "string",
              "tagPayloadUpdatedAt": "string",
              "tagEligibility": "string",
              "tagEditable": true,
              "systemTags": [
                {
                  "type": "string",
                  "text": "string",
                  "explanationKey": "string",
                  "evidence": {
                    "address": "string",
                    "origins": [
                      {
                        "origin": "string",
                        "displayName": "string",
                        "iconUrl": "string",
                        "lastUsedAt": "string"
                      }
                    ],
                    "matchedOrigin": "string",
                    "latestUsedAt": "string"
                  }
                }
              ]
            }
          },
          "lastReceivedAt": "string"
        }
      ]
    }
  ],
  "total": 0
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Query Parameters
purpose
address
chainId
token
dappOrigin
limit
offset
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/address-balances"

Create quote

POST/v1/accounts/{accountId}/quote🔒

Unified quote endpoint. For type=send: reserves balances and returns signing data. For type=swap: reserves balances and returns swap intents via Uniswap.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
idempotency-keyheaderstringClient-generated key for one account, HTTP operation, and exact request body. Reuse it only to retry that same operation; a completed retry returns the stored response. Keys expire after 24 hours.
Request Body
unknown
Swap Quote Request
typerequired"swap"
chainIdrequirednumber
Chain ID
tokenInrequiredstring
Token address being sold
tokenOutrequiredstring
Token address being bought
amountInstring
Amount to swap in smallest unit (stringified bigint). Required unless maxSend is true.
slippageMode"auto" | "manual"
Slippage selection mode. auto asks the route provider to calculate slippage; manual uses slippageBps. Responses omit slippageBps when the route has no explicit slippage value.
slippageBpsnumber
Manual slippage tolerance in basis points (e.g. 50 = 0.5%, max: 500 = 5%)
tokenOutChainIdnumber
Destination chain ID for cross-chain swaps
maxSendboolean
When true, server computes max swappable amount. amountIn is ignored.
spendableAddressesstring[]
singleAddressstring
Single-address mode: pin the swap to this owned address — inputs are selected only from it, the output (and bridge destination) is delivered to it, and any change stays on it. Cannot be combined with spendableAddresses.
destinationAddressstring
Optional address or ENS name that receives the swap/bridge output. Omit to receive into a fresh Cloaked address.
acknowledgedContractRecipientstring
Exact resolved contract address acknowledged by the user. Required only when the destination resolves to a smart contract.
Convert Request
typerequired"pool-deposit"
chainIdrequirednumber
Chain ID where the privacy pool lives
tokenrequiredstring
Token address to deposit (0x...)
amountstring
Deposit amount in smallest unit (stringified bigint). Required unless maxSend is true.
decimalsrequirednumber
Token decimals (0-255)
maxSendboolean
When true, server computes max deposit amount atomically. Amount field is ignored.
spendableAddressesstring[]
singleAddressstring
Single-address mode: pin the deposit to this owned address — inputs are selected only from it and any change stays on it. Cannot be combined with spendableAddresses.
precommitmentrequiredstring
Precommitment hash (stringified bigint) binding the deposit secrets without revealing them
nullifierHashrequiredstring
Hash of the commitment nullifier (stringified bigint). Lets the server cross-reference on-chain spends.
depositIndexnumber
Client-derived deposit index used for precommitment derivation. Falls back to server-computed index if omitted.
reservationstring
Signed reservation token returned by the pool-deposit reservation endpoint.
Pool Withdraw Quote Request
typerequired"pool-withdraw"
chainIdrequirednumber
Chain ID where the privacy pool lives
tokenrequiredstring
Token address to withdraw (0x...)
amountrequiredstring
Amount in smallest unit (stringified bigint)
amountMode"withdrawal" | "receive"
Whether amount is the gross pool withdrawal amount or exact post-fee receive amount.
maxSendboolean
Whether this quote should spend the selected commitments as a max flow.
decimalsrequirednumber
Token decimals (0-255)
destinationAddressrequiredstring
Recipient of the withdrawn funds: your own active clkd.eth name for a self-withdrawal (a fresh owned address is minted), or any 0x address / ENS / clkd.eth name for an incognito send to a third party.
commitmentIdrequiredstring (uuid)
Incognito balance commitment id to withdraw from.
Conversion Recover Request
typerequired"pool-recover"
chainIdrequirednumber
Chain ID where the privacy pool lives
tokenrequiredstring
Token address (0x...)
commitmentIdrequiredstring
DB ID of the declined commitment to recover
Boost Deposit Quote Request
typerequired"boost-deposit"
chainIdrequirednumber
Chain ID where the Privacy Boost pool lives
tokenrequiredstring
Source token to deposit (native sentinel for ETH)
amountrequiredstring
Deposit amount in smallest unit (stringified bigint)
decimalsrequirednumber
Token decimals (0-255)
unknown
Responses
200Default Response
Schema
Swap Quote Response
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
signingReviewobject
versionrequired1
intentsrequiredobject[]
userActionCallIndicesrequiredinteger[]
simulationCallIndicesinteger[]
calldataCaveatsobject[]
callIndexrequiredinteger
kindrequired"provider-calldata-suffix"
policyVersionrequired1
verifierrequiredstring
suffixLengthrequiredinteger
canonicalCalldataHashrequiredstring
suffixHashrequiredstring
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
expectedOutputrequiredstring
minimumOutputrequiredstring
outputTokenrequiredstring
outputDecimalsrequirednumber
outputSymbolrequiredstring
outputRecipientrequiredstring
outputRecipientOwnedrequiredboolean
Server-verified assertion that outputRecipient belongs to the authenticated Cloaked account.
recoveryRecipientstring
slippageModerequired"auto" | "manual"
slippageBpsnumber
Effective slippage tolerance in basis points. Omitted when the route has no explicit slippage value.
requestedSlippageBpsnumber
routingrequiredstring
bridgeProvider"uniswap" | "across"
protocolFeeBpsrequirednumber
protocolFeeAmountrequiredstring
amountInrequiredstring
selectedFundingSourcesobject[]
chainIdrequirednumber
tokenrequiredstring
addressrequiredstring
amountrequiredstring
Raw selected amount in smallest unit
idCountrequirednumber
Number of spendable output IDs represented by this selected funding source
addressSummaryrequiredobject
receiveCountrequirednumber
Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.
rawReceiveCountrequirednumber
Literal distinct inbound transfer/log count before trusted-action collapsing.
trustedReceiveActionCountrequirednumber
Number of Cloaked-managed receive actions collapsed into receiveCount.
trustedReceiveActionTypesrequiredstring[]
assetCountrequirednumber
Distinct chain-token assets seen for this address.
chainCountrequirednumber
Distinct networks seen for this address.
provenancerequiredobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
provenanceLabelGroupsobject
priceImpactnumber
estimatedFillTimeMsnumber
fillDeadlinenumber
planIdstring
Bridge routing plan identifier from Across protocol, present only for cross-chain (CHAINED) quotes
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
Conversion Recover Response
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
poolAddressrequiredstring
commitmentrequiredobject
idrequiredstring
depositIndexrequirednumber
withdrawalIndexrequirednumber
commitmentrequiredstring
labelrequiredstring
valuerequiredstring
depositorAddressrequiredstring
Stealth address that made the original deposit (msg.sender for ragequit).
Incognito Send Response
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
poolAddressrequiredstring
resolvedDestinationrequiredstring
destinationAddressNoncestring | null
Nonce used to derive the generated self-withdraw destination address.
destinationAvatarUrlrequiredstring | null
selfSendrequiredboolean
feeRecipientrequiredstring
Address to receive relay fees
relayFeeBPSrequirednumber
Definitive relay fee BPS for this set of commitments. Client bakes into each proof.
feePerProofrequiredstring
Estimated fee per ZK proof relay in the pool token units (stringified bigint)
maxRelayFeeBPSrequirednumber
On-chain contract maximum for relayFeeBPS
withdrawalAmountrequiredstring
Gross amount proven to the pool before relay fees are deducted.
receiveAmountrequiredstring
Amount delivered to the recipient after relay fees are deducted.
amountModerequired"withdrawal" | "receive"
Whether amount was quoted as a gross withdrawal amount or exact post-fee receive amount.
commitmentsrequiredobject[]
idrequiredstring
depositIndexrequirednumber
withdrawalIndexrequirednumber
commitmentrequiredstring
labelrequiredstring
valuerequiredstring
withdrawalAmountrequiredstring
pooledSincerequiredstring
ISO timestamp when the ASP approved this commitment (entered the anonymity set)
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
Convert Response
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
poolAddressrequiredstring
depositIndexrequirednumber
grossAmountrequiredstring
Total ETH sent to entrypoint (amount + vetting fee)
feeAmountrequiredstring
Vetting fee deducted by the pool
feeBpsrequirednumber
Vetting fee in basis points
netPoolValuerequiredstring
Net value credited to the pool commitment
cloakedFeeBpsrequirednumber
Cloaked protocol fee rate in basis points
cloakedFlatFeerequiredstring
Flat fee floor in wei for the Cloaked deposit fee
cloakieFeeModerequired"flat" | "standard"
Legacy fee mode: flat when the Cloaked deposit fee is waived, otherwise standard
selectedFundingSourcesobject[]
chainIdrequirednumber
tokenrequiredstring
addressrequiredstring
amountrequiredstring
Raw selected amount in smallest unit
idCountrequirednumber
Number of spendable output IDs represented by this selected funding source
addressSummaryrequiredobject
receiveCountrequirednumber
Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.
rawReceiveCountrequirednumber
Literal distinct inbound transfer/log count before trusted-action collapsing.
trustedReceiveActionCountrequirednumber
Number of Cloaked-managed receive actions collapsed into receiveCount.
trustedReceiveActionTypesrequiredstring[]
assetCountrequirednumber
Distinct chain-token assets seen for this address.
chainCountrequirednumber
Distinct networks seen for this address.
provenancerequiredobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
provenanceLabelGroupsobject
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
Batch Send Quote Response
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
signingReviewobject
versionrequired1
intentsrequiredobject[]
userActionCallIndicesrequiredinteger[]
simulationCallIndicesinteger[]
calldataCaveatsobject[]
callIndexrequiredinteger
kindrequired"provider-calldata-suffix"
policyVersionrequired1
verifierrequiredstring
suffixLengthrequiredinteger
canonicalCalldataHashrequiredstring
suffixHashrequiredstring
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
resolvedDestinationrequiredstring
destinationAvatarUrlrequiredstring | null
selfSendrequiredboolean
executionSimulation"passed"
sourceAssetsrequiredobject[]
chainIdrequirednumber
tokenrequiredstring
decimalsrequirednumber
symbolrequiredstring
amountrequiredstring
selectedFundingSourcesobject[]
chainIdrequirednumber
tokenrequiredstring
addressrequiredstring
amountrequiredstring
Raw selected amount in smallest unit
idCountrequirednumber
Number of spendable output IDs represented by this selected funding source
addressSummaryrequiredobject
receiveCountrequirednumber
Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.
rawReceiveCountrequirednumber
Literal distinct inbound transfer/log count before trusted-action collapsing.
trustedReceiveActionCountrequirednumber
Number of Cloaked-managed receive actions collapsed into receiveCount.
trustedReceiveActionTypesrequiredstring[]
assetCountrequirednumber
Distinct chain-token assets seen for this address.
chainCountrequirednumber
Distinct networks seen for this address.
provenancerequiredobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
provenanceLabelGroupsobject
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
feeTotalsrequiredobject
totalUsdAmountrequirednumber | null
Send Quote Response
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
signingReviewobject
versionrequired1
intentsrequiredobject[]
userActionCallIndicesrequiredinteger[]
simulationCallIndicesinteger[]
calldataCaveatsobject[]
callIndexrequiredinteger
kindrequired"provider-calldata-suffix"
policyVersionrequired1
verifierrequiredstring
suffixLengthrequiredinteger
canonicalCalldataHashrequiredstring
suffixHashrequiredstring
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
resolvedDestinationrequiredstring
destinationAvatarUrlrequiredstring | null
sourceAmountrequiredstring
Source amount selected for the send, in smallest units
selfSendrequiredboolean
executionSimulation"passed"
selectedFundingSourcesobject[]
chainIdrequirednumber
tokenrequiredstring
addressrequiredstring
amountrequiredstring
Raw selected amount in smallest unit
idCountrequirednumber
Number of spendable output IDs represented by this selected funding source
addressSummaryrequiredobject
receiveCountrequirednumber
Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.
rawReceiveCountrequirednumber
Literal distinct inbound transfer/log count before trusted-action collapsing.
trustedReceiveActionCountrequirednumber
Number of Cloaked-managed receive actions collapsed into receiveCount.
trustedReceiveActionTypesrequiredstring[]
assetCountrequirednumber
Distinct chain-token assets seen for this address.
chainCountrequirednumber
Distinct networks seen for this address.
provenancerequiredobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
provenanceLabelGroupsobject
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
Boost Deposit Quote Response
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
submissionSignaturerequiredstring
Server authorization binding this experimental quote to its exact submission
poolAddressrequiredstring
depositAmountrequiredstring
Shielded deposit amount in the token smallest unit
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
Dapp Address Prepared Response
preparedrequiredtrue
addressrequiredstring
chainIdrequirednumber
expectedCoderequiredstring
signaturerequiredstring
Dapp Call Quote Response
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
quoteIdrequiredstring
expiresAtrequiredstring
signaturerequiredstring
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
feePaymentrequiredobject
tokenrequiredstring
symbolrequiredstring
decimalsrequirednumber
availablerequiredstring
maxSpendablerequiredstring
executionSimulationrequired"passed"
calldataCaveatsobject[]
callIndexrequiredinteger
kindrequired"provider-calldata-suffix"
policyVersionrequired1
verifierrequiredstring
suffixLengthrequiredinteger
canonicalCalldataHashrequiredstring
suffixHashrequiredstring
preparationRequiredtrue
expectedCodestring
Group Send Quote Response
quoteIdrequiredstring
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
expiresAtrequiredstring
json
{
  "intents": [
    {
      "chainId": 0,
      "eoa": "string",
      "executionData": "string",
      "nonce": "string",
      "derivationNonce": "string",
      "payer": "string",
      "paymentToken": "string",
      "paymentMaxAmount": "string",
      "combinedGas": "string",
      "encodedPreCalls": [
        "string"
      ],
      "encodedFundTransfers": [
        "string"
      ],
      "settler": "string",
      "expiry": "string",
      "isMultichain": true,
      "funder": "string",
      "funderSignature": "string",
      "settlerContext": "string",
      "paymentAmount": "string",
      "paymentRecipient": "string",
      "paymentSignature": "string",
      "supportedAccountImplementation": "string",
      "domain": {
        "name": "string",
        "version": "string",
        "chainId": 0,
        "verifyingContract": "string"
      },
      "types": null,
      "primaryType": "string"
    }
  ],
  "delegations": [
    {
      "chainId": 0,
      "address": "string",
      "contractAddress": "string",
      "derivationNonce": 0,
      "authorizationNonce": 0
    }
  ],
  "signingReview": {
    "version": 0,
    "intents": [
      {
        "userActionCallIndices": [
          null
        ],
        "simulationCallIndices": [
          null
        ],
        "calldataCaveats": [
          {
            "callIndex": null,
            "kind": "string",
            "policyVersion": 0,
            "verifier": "string",
            "suffixLength": null,
            "canonicalCalldataHash": "string",
            "suffixHash": "string"
          }
        ]
      }
    ]
  },
  "quoteId": "string",
  "expiresAt": "string",
  "signature": "string",
  "expectedOutput": "string",
  "minimumOutput": "string",
  "outputToken": "string",
  "outputDecimals": 0,
  "outputSymbol": "string",
  "outputRecipient": "string",
  "outputRecipientOwned": true,
  "recoveryRecipient": "string",
  "slippageMode": "string",
  "slippageBps": 0,
  "requestedSlippageBps": 0,
  "routing": "string",
  "bridgeProvider": "string",
  "protocolFeeBps": 0,
  "protocolFeeAmount": "string",
  "amountIn": "string",
  "selectedFundingSources": [
    {
      "chainId": 0,
      "token": "string",
      "address": "string",
      "amount": "string",
      "idCount": 0,
      "addressSummary": {
        "receiveCount": 0,
        "rawReceiveCount": 0,
        "trustedReceiveActionCount": 0,
        "trustedReceiveActionTypes": [
          "string"
        ],
        "assetCount": 0,
        "chainCount": 0
      },
      "provenance": {
        "status": "string",
        "outputSystemTags": [
          {
            "type": "string",
            "provider": "string",
            "text": "string",
            "explanationKey": "string",
            "evidence": {
              "chainId": null,
              "txHash": "string",
              "transferOrLogIndex": null,
              "receiveFromAddress": "string",
              "poolAddress": "string",
              "entrypointAddress": "string",
              "poolTransferOrLogIndex": null
            }
          }
        ],
        "sourceLabelGroupId": "string",
        "olderFundsCount": null,
        "unresolvedReasons": [
          "string"
        ],
        "displayContext": {
          "reason": "string",
          "currentOutputCount": null,
          "sourceCount": null,
          "actionTypes": [
            "string"
          ]
        },
        "funding": {
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ]
        },
        "association": {
          "status": "string",
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ],
          "ignoredUnsolicitedCount": null,
          "summary": {
            "sourceCount": null,
            "userTaggedSourceCount": null,
            "untaggedSourceCount": null,
            "olderFundsCount": null,
            "unknownCount": null
          }
        },
        "display": {
          "badgeKind": "string",
          "label": "string",
          "fundingLabel": "string",
          "associationLabel": "string"
        },
        "editableSource": {
          "id": "string",
          "kind": "string",
          "origin": {
            "chainId": null,
            "txHash": "string",
            "transferOrLogIndex": null
          },
          "address": "string",
          "tagPayloadCiphertext": "string",
          "tagPayloadUpdatedAt": "string",
          "tagEligibility": "string",
          "tagEditable": true,
          "systemTags": [
            {
              "type": "string",
              "text": "string",
              "explanationKey": "string",
              "evidence": {
                "address": "string",
                "origins": [
                  {
                    "origin": "string",
                    "displayName": "string",
                    "iconUrl": "string",
                    "lastUsedAt": "string"
                  }
                ],
                "matchedOrigin": "string",
                "latestUsedAt": "string"
              }
            }
          ]
        }
      }
    }
  ],
  "provenanceLabelGroups": null,
  "priceImpact": 0,
  "estimatedFillTimeMs": 0,
  "fillDeadline": 0,
  "planId": "string",
  "fees": {
    "network": "string",
    "dust": "string",
    "service": "string",
    "networkUsdAmount": 0,
    "totalUsdAmount": 0,
    "vetting": "string",
    "deposit": "string",
    "total": "string",
    "waived": true
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
409Default Response
Schema
errorrequiredstring
e.g. "Conflict"
messagerequiredstring
codestring
e.g. "QUOTE_LOCK_CONFLICT"
json
{
  "error": "Conflict",
  "message": "string",
  "code": "QUOTE_LOCK_CONFLICT"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 30 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 30 requests per 1 minute."
}
451Default Response
Schema
errorrequiredstring
e.g. "Unavailable"
messagerequiredstring
code"GEO_RESTRICTED" | "TOKENIZED_ASSET_GEO_RESTRICTED"
recoveryUrlstring
json
{
  "error": "Unavailable",
  "message": "string",
  "code": "string",
  "recoveryUrl": "string"
}
502Default Response
Schema
errorrequiredstring
e.g. "Bad Gateway"
messagerequiredstring
codestring
e.g. "SWAP_UNAVAILABLE"
json
{
  "error": "Bad Gateway",
  "message": "string",
  "code": "SWAP_UNAVAILABLE"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Headers
idempotency-key
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "type": "",
  "chainId": 0,
  "token": "",
  "amount": "",
  "decimals": 0,
  "destinationAddress": "",
  "spendableAddresses": [
    ""
  ],
  "singleAddress": "",
  "maxSend": true,
  "executionSimulation": "",
  "ttl": 0
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/quote"

Submit transaction

POST/v1/accounts/{accountId}/submit🔒

Submit client-signed intents and delegations from a quote to relay the transaction on-chain. Validates signatures, checks price slippage, and submits via the server relayer so the user pays no gas directly.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
idempotency-keyheaderstringClient-generated key for one account, HTTP operation, and exact request body. Reuse it only to retry that same operation; a completed retry returns the stored response. Keys expire after 24 hours.
Request Body
Porto Submit Request
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
signaturerequiredstring
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
signaturerequiredstring
quoteIdrequiredstring
Quote ID from quote response
submissionSignaturestring
Server authorization required for quotes that do not yet have a persisted transaction intent
recoverCalldatastring
Canonical encoded Pool.ragequit(proof) calldata (hex)
Pool Withdraw Submit Request
quoteIdrequiredstring
Quote ID from pool-withdraw quote response
withdrawalsrequiredobject[]
commitmentIdrequiredstring
Pool commitment DB ID
calldatarequiredstring
Encoded Entrypoint.relay() calldata (hex)
changeNullifierHashstring
Nullifier hash of the change commitment created by a partial withdrawal (stringified bigint)
Conversion Recover Submit Request
quoteIdrequiredstring
Quote ID from pool-recover quote response
recoverCalldatarequiredstring
Canonical encoded Pool.ragequit(proof) calldata (hex)
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
signaturerequiredstring
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
signaturerequiredstring
Responses
200Default Response
Schema
successrequiredboolean
quoteIdrequiredstring
statusrequiredstring
messagerequiredstring
json
{
  "success": true,
  "quoteId": "string",
  "status": "string",
  "message": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
409Default Response
Schema
errorrequiredstring
e.g. "Conflict"
messagerequiredstring
codestring
e.g. "QUOTE_LOCK_CONFLICT"
json
{
  "error": "Conflict",
  "message": "string",
  "code": "QUOTE_LOCK_CONFLICT"
}
451Default Response
Schema
errorrequiredstring
e.g. "Unavailable"
messagerequiredstring
code"GEO_RESTRICTED" | "TOKENIZED_ASSET_GEO_RESTRICTED"
recoveryUrlstring
json
{
  "error": "Unavailable",
  "message": "string",
  "code": "string",
  "recoveryUrl": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Headers
idempotency-key
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "intents": [
    {
      "chainId": 0,
      "eoa": "",
      "executionData": "",
      "nonce": "",
      "derivationNonce": "",
      "payer": "",
      "paymentToken": "",
      "paymentMaxAmount": "",
      "combinedGas": "",
      "encodedPreCalls": [
        ""
      ],
      "encodedFundTransfers": [
        ""
      ],
      "settler": "",
      "expiry": "",
      "isMultichain": true,
      "funder": "",
      "funderSignature": "",
      "settlerContext": "",
      "paymentAmount": "",
      "paymentRecipient": "",
      "paymentSignature": "",
      "supportedAccountImplementation": "",
      "domain": {
        "name": "",
        "version": "",
        "chainId": 0,
        "verifyingContract": ""
      },
      "types": null,
      "primaryType": "",
      "signature": ""
    }
  ],
  "delegations": [
    {
      "chainId": 0,
      "address": "",
      "contractAddress": "",
      "derivationNonce": 0,
      "authorizationNonce": 0,
      "signature": ""
    }
  ],
  "quoteId": "",
  "submissionSignature": "",
  "recoverCalldata": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/submit"

Get relay status

GET/v1/accounts/{accountId}/relay-status/{quoteId}🔒

Get the relay transaction status and hash for a submitted quote.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)—
quoteId*pathstring—
Responses
200Default Response
Schema
statusrequiredstring
chainIdrequirednumber
txHashrequiredstring | null
confirmedTxHashrequiredstring | null
json
{
  "status": "string",
  "chainId": 0,
  "txHash": "string",
  "confirmedTxHash": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
Try it
Path Parameters
accountId
quoteId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/relay-status/{quoteId}"

Unlock quote

POST/v1/accounts/{accountId}/unlock🔒

Release the lock held by a quote so the funds become available for a new transaction. Use when the user cancels a send or the client decides not to submit.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
quoteIdrequiredstring
Quote ID from quote response
Responses
200Default Response
Schema
successrequiredboolean
messagerequiredstring
json
{
  "success": true,
  "message": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
451Default Response
Schema
errorrequiredstring
e.g. "Unavailable"
messagerequiredstring
code"GEO_RESTRICTED" | "TOKENIZED_ASSET_GEO_RESTRICTED"
recoveryUrlstring
json
{
  "error": "Unavailable",
  "message": "string",
  "code": "string",
  "recoveryUrl": "string"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/unlock"

Get max spendable

POST/v1/accounts/{accountId}/max-spendable🔒

Calculate the maximum spendable amount for a token, accounting for relay fees, swap gas, and pool fees when applicable. Use this to power the "max" button in send, swap, and pool UIs.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
chainIdrequirednumber
Chain ID (must support Porto)
tokenrequiredstring
Token address (0x...)
typerequired"send" | "swap" | "pool-deposit" | "boost-deposit"
Transaction type — swap, pool-deposit, and boost-deposit subtract additional gas/service fees
tokenOutstring
Token address to buy (required for type=swap)
slippageMode"auto" | "manual"
Slippage mode for swap max-spendable. auto asks the route provider to calculate slippage; manual uses slippageBps. Responses omit slippageBps when the route has no explicit slippage value.
slippageBpsnumber
Manual slippage tolerance in bps (type=swap, 1-500)
tokenOutChainIdnumber
Destination chain ID for cross-chain swaps
spendableAddressesstring[]
Optional address-held funding sources to use exactly for this max calculation.
singleAddressstring
Single-address mode: compute the max using only this owned address. Cannot be combined with spendableAddresses.
destinationAddressstring
Optional address or ENS name that receives swap output. ENS is resolved only for the final quote.
Responses
200Default Response
Schema
maxAmountrequiredstring
Maximum spendable amount in smallest unit
feeEstimaterequiredstring
Estimated fee in smallest unit
feeEstimateUsdAmountnumber | null
USD value of feeEstimate, or null when USD pricing is unavailable
spendableCountrequirednumber
Number of spendable UTXOs that will be consumed
grossAmountstring
Gross deposit amount including vetting fee (pool-deposit only)
feesobject
networkrequiredstring
Gas/relay fee estimate
vettingrequiredstring
On-chain vetting fee
depositrequiredstring
Cloaked service fee (0 if waived)
servicerequiredstring
Vetting + deposit combined
totalrequiredstring
Network + service total
protocolFeeBpsnumber
Protocol fee rate in bps (swap only)
protocolFeeAmountstring
Protocol fee amount in smallest unit (swap only)
json
{
  "maxAmount": "string",
  "feeEstimate": "string",
  "feeEstimateUsdAmount": 0,
  "spendableCount": 0,
  "grossAmount": "string",
  "fees": {
    "network": "string",
    "vetting": "string",
    "deposit": "string",
    "service": "string",
    "total": "string"
  },
  "protocolFeeBps": 0,
  "protocolFeeAmount": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
451Default Response
Schema
errorrequiredstring
e.g. "Unavailable"
messagerequiredstring
code"GEO_RESTRICTED" | "TOKENIZED_ASSET_GEO_RESTRICTED"
recoveryUrlstring
json
{
  "error": "Unavailable",
  "message": "string",
  "code": "string",
  "recoveryUrl": "string"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "chainId": 0,
  "token": "",
  "type": "",
  "tokenOut": "",
  "slippageMode": "",
  "slippageBps": 0,
  "tokenOutChainId": 0,
  "spendableAddresses": [
    ""
  ],
  "singleAddress": "",
  "destinationAddress": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/max-spendable"

Create pool deposit reservation

POST/v1/accounts/{accountId}/pool-deposit-reservations🔒

Reserve funding inputs and return the exact privacy-pool deposit values for review before wallet authentication.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
chainIdrequirednumber
Chain ID where the privacy pool lives
tokenrequiredstring
Token address to deposit (0x...)
amountstring
Deposit amount in smallest unit (stringified bigint). Required unless maxSend is true.
decimalsrequirednumber
Token decimals (0-255)
maxSendboolean
When true, server computes max deposit amount atomically. Amount field is ignored.
spendableAddressesstring[]
singleAddressstring
Single-address mode: pin the deposit to this owned address — inputs are selected only from it and any change stays on it. Cannot be combined with spendableAddresses.
Responses
200Default Response
Schema
quoteIdrequiredstring
Lock ID for cancellation and finalization
expiresAtrequiredstring
ISO expiry for the temporary funding lock
reservationrequiredstring
Opaque signed token required to finalize this reservation
signaturerequiredstring
Signature over the complete review response
poolAddressrequiredstring
grossAmountrequiredstring
Total amount sent to the pool entrypoint including vetting fee
feeAmountrequiredstring
Vetting fee deducted by the pool
feeBpsrequirednumber
Vetting fee in basis points
netPoolValuerequiredstring
Estimated net value credited to the private pool balance
cloakedFeeBpsrequirednumber
Cloaked protocol fee rate in basis points
cloakedFlatFeerequiredstring
cloakieFeeModerequired"flat" | "standard"
selectedFundingSourcesobject[]
chainIdrequirednumber
tokenrequiredstring
addressrequiredstring
amountrequiredstring
Raw selected amount in smallest unit
idCountrequirednumber
Number of spendable output IDs represented by this selected funding source
addressSummaryrequiredobject
receiveCountrequirednumber
Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.
rawReceiveCountrequirednumber
Literal distinct inbound transfer/log count before trusted-action collapsing.
trustedReceiveActionCountrequirednumber
Number of Cloaked-managed receive actions collapsed into receiveCount.
trustedReceiveActionTypesrequiredstring[]
assetCountrequirednumber
Distinct chain-token assets seen for this address.
chainCountrequirednumber
Distinct networks seen for this address.
provenancerequiredobject
statusrequired"resolved" | "unavailable"
outputSystemTagsrequiredobject[]
System tags that describe only the exact current output and never propagate to successor outputs.
typerequired"privacy-provider-origin"
providerrequired"privacy-pools" | "privacy-boost"
textrequiredstring
Short server-derived tag text for display
explanationKeyrequired"privacy_provider_origin"
evidencerequiredobject
chainIdrequiredinteger
txHashrequiredstring
transferOrLogIndexrequiredinteger
receiveFromAddressrequiredstring
poolAddressrequiredstring
entrypointAddressrequiredstring
poolTransferOrLogIndexrequiredinteger | null
sourceLabelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
Number of pre-launch checkpoint provenance markers represented by this balance.
unresolvedReasonsrequiredstring[]
displayContextrequiredobject
reasonrequired"fresh_receive" | "cloaked_action_output" | "mixed_current_outputs" | "carried_source" | "older_funds" | "unavailable"
currentOutputCountrequiredinteger
sourceCountrequiredinteger
actionTypesrequiredstring[]
fundingrequiredobject
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
associationrequiredobject
statusrequired"clean" | "linked" | "unknown"
labelGroupIdrequiredstring | null
olderFundsCountrequiredinteger
unresolvedReasonsrequiredstring[]
ignoredUnsolicitedCountrequiredinteger
summaryrequiredobject
sourceCountrequiredinteger
userTaggedSourceCountrequiredinteger
untaggedSourceCountrequiredinteger
olderFundsCountrequiredinteger
unknownCountrequiredinteger
displayrequiredobject
badgeKindrequired"tagged" | "mixed" | "older_funds" | "unknown" | "untagged"
labelrequiredstring | null
fundingLabelrequiredstring | null
associationLabelrequiredstring | null
editableSourcerequiredobject | null
The single directly editable receive source for this item, when one exists.
provenanceLabelGroupsobject
feesrequiredobject
networkrequiredstring
Gas/relay fee in wei (gas cost only, excludes dust)
duststring
Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.
servicerequiredstring
Protocol fees in wei (vetting + cloaked, or swap protocol fee)
networkUsdAmountnumber | null
USD value of the network fee, or null when USD pricing is unavailable
totalUsdAmountnumber | null
USD value of the total fee, or null when USD pricing is unavailable
vettingstring
On-chain vetting fee in wei (pool deposits only)
depositstring
Cloaked deposit fee in wei (pool deposits only)
totalrequiredstring
Total fees in wei (network + dust + service)
waivedboolean
True when fees are waived (e.g. Cloakie holder on swaps)
json
{
  "quoteId": "string",
  "expiresAt": "string",
  "reservation": "string",
  "signature": "string",
  "poolAddress": "string",
  "grossAmount": "string",
  "feeAmount": "string",
  "feeBps": 0,
  "netPoolValue": "string",
  "cloakedFeeBps": 0,
  "cloakedFlatFee": "string",
  "cloakieFeeMode": "string",
  "selectedFundingSources": [
    {
      "chainId": 0,
      "token": "string",
      "address": "string",
      "amount": "string",
      "idCount": 0,
      "addressSummary": {
        "receiveCount": 0,
        "rawReceiveCount": 0,
        "trustedReceiveActionCount": 0,
        "trustedReceiveActionTypes": [
          "string"
        ],
        "assetCount": 0,
        "chainCount": 0
      },
      "provenance": {
        "status": "string",
        "outputSystemTags": [
          {
            "type": "string",
            "provider": "string",
            "text": "string",
            "explanationKey": "string",
            "evidence": {
              "chainId": null,
              "txHash": "string",
              "transferOrLogIndex": null,
              "receiveFromAddress": "string",
              "poolAddress": "string",
              "entrypointAddress": "string",
              "poolTransferOrLogIndex": null
            }
          }
        ],
        "sourceLabelGroupId": "string",
        "olderFundsCount": null,
        "unresolvedReasons": [
          "string"
        ],
        "displayContext": {
          "reason": "string",
          "currentOutputCount": null,
          "sourceCount": null,
          "actionTypes": [
            "string"
          ]
        },
        "funding": {
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ]
        },
        "association": {
          "status": "string",
          "labelGroupId": "string",
          "olderFundsCount": null,
          "unresolvedReasons": [
            "string"
          ],
          "ignoredUnsolicitedCount": null,
          "summary": {
            "sourceCount": null,
            "userTaggedSourceCount": null,
            "untaggedSourceCount": null,
            "olderFundsCount": null,
            "unknownCount": null
          }
        },
        "display": {
          "badgeKind": "string",
          "label": "string",
          "fundingLabel": "string",
          "associationLabel": "string"
        },
        "editableSource": {
          "id": "string",
          "kind": "string",
          "origin": {
            "chainId": null,
            "txHash": "string",
            "transferOrLogIndex": null
          },
          "address": "string",
          "tagPayloadCiphertext": "string",
          "tagPayloadUpdatedAt": "string",
          "tagEligibility": "string",
          "tagEditable": true,
          "systemTags": [
            {
              "type": "string",
              "text": "string",
              "explanationKey": "string",
              "evidence": {
                "address": "string",
                "origins": [
                  {
                    "origin": "string",
                    "displayName": "string",
                    "iconUrl": "string",
                    "lastUsedAt": "string"
                  }
                ],
                "matchedOrigin": "string",
                "latestUsedAt": "string"
              }
            }
          ]
        }
      }
    }
  ],
  "provenanceLabelGroups": null,
  "fees": {
    "network": "string",
    "dust": "string",
    "service": "string",
    "networkUsdAmount": 0,
    "totalUsdAmount": 0,
    "vetting": "string",
    "deposit": "string",
    "total": "string",
    "waived": true
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
409Default Response
Schema
errorrequiredstring
e.g. "Conflict"
messagerequiredstring
codestring
e.g. "QUOTE_LOCK_CONFLICT"
json
{
  "error": "Conflict",
  "message": "string",
  "code": "QUOTE_LOCK_CONFLICT"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 30 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 30 requests per 1 minute."
}
451Default Response
Schema
errorrequiredstring
e.g. "Unavailable"
messagerequiredstring
code"GEO_RESTRICTED" | "TOKENIZED_ASSET_GEO_RESTRICTED"
recoveryUrlstring
json
{
  "error": "Unavailable",
  "message": "string",
  "code": "string",
  "recoveryUrl": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "chainId": 0,
  "token": "",
  "amount": "",
  "decimals": 0,
  "maxSend": true,
  "spendableAddresses": [
    ""
  ],
  "singleAddress": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/pool-deposit-reservations"

Create swap preview

POST/v1/accounts/{accountId}/swap-preview🔒

Get a swap preview (price discovery) without reserving balances.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
chainIdrequirednumber
Chain ID
tokenInrequiredstring
Token address being sold
tokenOutrequiredstring
Token address being bought
amountInrequiredstring
Amount to swap in smallest unit (stringified bigint)
slippageMode"auto" | "manual"
Slippage selection mode. auto asks the route provider to calculate slippage; manual uses slippageBps. Responses omit slippageBps when the route has no explicit slippage value.
slippageBpsnumber
Manual slippage tolerance in basis points (e.g. 50 = 0.5%, max: 500 = 5%)
tokenOutChainIdnumber
Destination chain ID for cross-chain swaps
spendableAddressesstring[]
Optional address-held funding sources to use exactly for this swap preview.
singleAddressstring
Single-address mode: preview using only this owned address. Cannot be combined with spendableAddresses.
destinationAddressstring
Optional address or ENS name that receives swap output. ENS is resolved only for the final quote.
Responses
200Default Response
Schema
expectedOutputrequiredstring
minimumOutputrequiredstring
outputTokenrequiredstring
outputDecimalsrequirednumber
outputSymbolrequiredstring
routingrequiredstring
slippageModerequired"auto" | "manual"
slippageBpsnumber
Effective slippage tolerance in basis points. Omitted when the route has no explicit slippage value.
requestedSlippageBpsnumber
feeEstimaterequiredstring
estimatedFillTimeMsnumber
protocolFeeBpsrequirednumber
protocolFeeAmountrequiredstring
priceImpactnumber
rateOnlyboolean
json
{
  "expectedOutput": "string",
  "minimumOutput": "string",
  "outputToken": "string",
  "outputDecimals": 0,
  "outputSymbol": "string",
  "routing": "string",
  "slippageMode": "string",
  "slippageBps": 0,
  "requestedSlippageBps": 0,
  "feeEstimate": "string",
  "estimatedFillTimeMs": 0,
  "protocolFeeBps": 0,
  "protocolFeeAmount": "string",
  "priceImpact": 0,
  "rateOnly": true
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 30 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 30 requests per 1 minute."
}
451Default Response
Schema
errorrequiredstring
e.g. "Unavailable"
messagerequiredstring
code"GEO_RESTRICTED" | "TOKENIZED_ASSET_GEO_RESTRICTED"
recoveryUrlstring
json
{
  "error": "Unavailable",
  "message": "string",
  "code": "string",
  "recoveryUrl": "string"
}
502Default Response
Schema
errorrequiredstring
e.g. "Bad Gateway"
messagerequiredstring
codestring
e.g. "SWAP_UNAVAILABLE"
json
{
  "error": "Bad Gateway",
  "message": "string",
  "code": "SWAP_UNAVAILABLE"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "chainId": 0,
  "tokenIn": "",
  "tokenOut": "",
  "amountIn": "",
  "slippageMode": "",
  "slippageBps": 0,
  "tokenOutChainId": 0,
  "spendableAddresses": [
    ""
  ],
  "singleAddress": "",
  "destinationAddress": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/swap-preview"

Recover conversion prepare

POST/v1/accounts/{accountId}/pool-recover/prepare🔒

Build an unsigned Porto intent and delegation for a pool recover (ragequit). The client calls this after generating the commitment proof, signs the returned intent and delegation, then submits via the standard submit endpoint.

Parameters
NameInTypeDescription
accountId*pathstring—
Request Body
quoteIdrequiredstring
Quote ID from pool-recover quote response
recoverCalldatarequiredstring
Canonical encoded Pool.ragequit(proof) calldata (hex)
Responses
200Default Response
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": "",
  "recoverCalldata": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/pool-recover/prepare"

Get pool state

GET/v1/accounts/{accountId}/pool/state🔒

Get the current incognito pool state for an account and token. Returns the Merkle tree, ASP leaves, and your commitments — everything the client needs to build ZK withdrawal proofs.

Parameters
NameInTypeDescription
chainId*querynumberChain ID of the pool
token*querystringToken address accepted by the pool (0x...)
purposequeryanyWhen set to withdraw, the route returns POOL_STATE_REFRESHING unless proof inputs are ready.
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
leavesrequiredstring[]
State tree leaves in insertion order (stringified bigints)
currentRootrequiredstring
Current Merkle root (stringified bigint)
treeSizerequirednumber
Number of leaves in the tree
aspLeavesstring[]
ASP-approved labels. In dev: from DB. In staging/production: verified against Entrypoint.latestRoot before being served.
spentNullifiersrequiredobject[]
All spent nullifiers from Withdrawn events — used for spent detection and change commitment discovery
nullifierHashrequiredstring
Spent nullifier hash (stringified bigint)
withdrawnValuerequiredstring
Withdrawn amount in wei (stringified bigint)
newCommitmentrequiredstring
Change commitment hash (stringified bigint)
nextDepositIndexrequirednumber
Next available deposit index for this account — use for precommitment derivation
commitmentsrequiredobject[]
This account's unspent pool commitments
idrequiredstring
Commitment DB ID
depositIndexrequirednumber
withdrawalIndexrequirednumber
commitmentrequiredstring
On-chain commitment hash
labelrequiredstring
On-chain label
valuerequiredstring
Commitment value in wei
aspStatusrequired"pending" | "approved" | "declined"
ASP approval status
json
{
  "leaves": [
    "string"
  ],
  "currentRoot": "string",
  "treeSize": 0,
  "aspLeaves": [
    "string"
  ],
  "spentNullifiers": [
    {
      "nullifierHash": "string",
      "withdrawnValue": "string",
      "newCommitment": "string"
    }
  ],
  "nextDepositIndex": 0,
  "commitments": [
    {
      "id": "string",
      "depositIndex": 0,
      "withdrawalIndex": 0,
      "commitment": "string",
      "label": "string",
      "value": "string",
      "aspStatus": "string"
    }
  ]
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Query Parameters
chainId
token
purpose
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/pool/state"

Get pool commitments

GET/v1/accounts/{accountId}/pool/commitments🔒

Get this account's current incognito commitments for a supported pool without loading Merkle proof state.

Parameters
NameInTypeDescription
chainId*querynumberChain ID of the pool
token*querystringToken address accepted by the pool (0x...)
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
commitmentsrequiredobject[]
This account's unspent pool commitments
idrequiredstring
Commitment DB ID
depositIndexrequirednumber
withdrawalIndexrequirednumber
commitmentrequiredstring
On-chain commitment hash
labelrequiredstring
On-chain label
valuerequiredstring
Commitment value in wei
aspStatusrequired"pending" | "approved" | "declined"
ASP approval status
json
{
  "commitments": [
    {
      "id": "string",
      "depositIndex": 0,
      "withdrawalIndex": 0,
      "commitment": "string",
      "label": "string",
      "value": "string",
      "aspStatus": "string"
    }
  ]
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
Try it
Path Parameters
accountId
Query Parameters
chainId
token
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/pool/commitments"

Reconcile pool commitment asp decline

POST/v1/accounts/{accountId}/pool/commitments/reconcile-asp-decline🔒

Confirm that Privacy Pools explicitly declined a previously approved commitment, mark it recoverable, and release its unused withdrawal quote.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
commitmentIdrequiredstring (uuid)
Selected pool commitment ID
quoteIdrequiredstring (uuid)
Unused pool-withdraw quote ID
Responses
200Default Response
Schema
successrequiredtrue
coderequired"POOL_DEPOSIT_DECLINED_AFTER_APPROVAL"
messagerequiredstring
json
{
  "success": true,
  "code": "string",
  "message": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
409Default Response
Schema
errorrequiredstring
e.g. "Conflict"
messagerequiredstring
codestring
e.g. "QUOTE_LOCK_CONFLICT"
json
{
  "error": "Conflict",
  "message": "string",
  "code": "QUOTE_LOCK_CONFLICT"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "commitmentId": "",
  "quoteId": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/pool/commitments/reconcile-asp-decline"

Cloakie

Cloakie NFT verification and withdrawal

Verify cloakie deposit

POST/v1/accounts/{accountId}/cloakie/verify🔒

Scan recent unused stealth addresses for Cloakie NFTs on Base. Records any newly discovered deposits and activates the fee waiver.

Parameters
NameInTypeDescription
accountId*pathstring—
Responses
200Default Response
Schema
activerequiredboolean
depositsrequiredobject[]
depositAddressrequiredstring
tokenIdrequiredstring | null
imageUrlrequiredstring | null
json
{
  "active": true,
  "deposits": [
    {
      "depositAddress": "string",
      "tokenId": "string",
      "imageUrl": "string"
    }
  ]
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
Try it
Path Parameters
accountId
curl -X POST \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/cloakie/verify"

Withdraw cloakie

POST/v1/accounts/{accountId}/cloakie/withdraw🔒

Build an intent to transfer a Cloakie NFT from a deposit address back to the user. Returns intents and delegations for client signing.

Parameters
NameInTypeDescription
accountId*pathstring—
Request Body
depositAddressrequiredstring
Stealth address holding the Cloakie
recipientAddressrequiredstring
Address to send the Cloakie to
tokenIdstring
Token ID of the Cloakie to withdraw (required if multiple at same address)
Responses
200Default Response
Schema
quoteIdrequiredstring
intentsrequiredobject[]
chainIdrequirednumber
eoarequiredstring
executionDatarequiredstring
noncerequiredstring
derivationNoncerequiredstring
payerrequiredstring
paymentTokenrequiredstring
paymentMaxAmountrequiredstring
combinedGasrequiredstring
encodedPreCallsrequiredstring[]
encodedFundTransfersrequiredstring[]
settlerrequiredstring
expiryrequiredstring
isMultichainrequiredboolean
funderrequiredstring
funderSignaturerequiredstring
settlerContextrequiredstring
paymentAmountrequiredstring
paymentRecipientrequiredstring
paymentSignaturerequiredstring
supportedAccountImplementationrequiredstring
domainrequiredobject
namerequiredstring
versionrequiredstring
chainIdrequirednumber
verifyingContractrequiredstring
typesrequiredany
EIP-712 type definitions
primaryTyperequired"Intent"
delegationsrequiredobject[]
chainIdrequirednumber
addressrequiredstring
contractAddressrequiredstring
derivationNoncerequirednumber
authorizationNoncerequirednumber
expiresAtrequiredstring
signaturerequiredstring
depositAddressrequiredstring
recipientAddressrequiredstring
tokenIdrequiredstring
json
{
  "quoteId": "string",
  "intents": [
    {
      "chainId": 0,
      "eoa": "string",
      "executionData": "string",
      "nonce": "string",
      "derivationNonce": "string",
      "payer": "string",
      "paymentToken": "string",
      "paymentMaxAmount": "string",
      "combinedGas": "string",
      "encodedPreCalls": [
        "string"
      ],
      "encodedFundTransfers": [
        "string"
      ],
      "settler": "string",
      "expiry": "string",
      "isMultichain": true,
      "funder": "string",
      "funderSignature": "string",
      "settlerContext": "string",
      "paymentAmount": "string",
      "paymentRecipient": "string",
      "paymentSignature": "string",
      "supportedAccountImplementation": "string",
      "domain": {
        "name": "string",
        "version": "string",
        "chainId": 0,
        "verifyingContract": "string"
      },
      "types": null,
      "primaryType": "string"
    }
  ],
  "delegations": [
    {
      "chainId": 0,
      "address": "string",
      "contractAddress": "string",
      "derivationNonce": 0,
      "authorizationNonce": 0
    }
  ],
  "expiresAt": "string",
  "signature": "string",
  "depositAddress": "string",
  "recipientAddress": "string",
  "tokenId": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
Try it
Path Parameters
accountId
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "depositAddress": "",
  "recipientAddress": "",
  "tokenId": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/cloakie/withdraw"

Relayer

Relayer details

GET/relayer/details

Get relayer fee info for a given chain and asset

Parameters
NameInTypeDescription
chainId*querynumberChain ID
assetAddress*querystringAsset address
Responses
200Default Response
Schema
feeBPSrequiredstring
feeReceiverAddressrequiredstring
chainIdrequirednumber
assetAddressrequiredstring
minWithdrawAmountrequiredstring
maxGasPricerequiredstring
json
{
  "feeBPS": "string",
  "feeReceiverAddress": "string",
  "chainId": 0,
  "assetAddress": "string",
  "minWithdrawAmount": "string",
  "maxGasPrice": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Query Parameters
chainId
assetAddress
curl -X GET \
  "https://api-stg.clkd.xyz/relayer/details"

Relayer quote

POST/relayer/quote

Get a fee commitment for relaying a privacy pool withdrawal

Request Body
chainIdrequirednumber
Chain ID
amountrequiredstring
Withdrawal amount in smallest token unit
assetrequiredstring
Asset address
recipientrequiredstring
Recipient address
extraGasboolean
Fund recipient with gas
Responses
200Default Response
Schema
baseFeeBPSrequiredstring
feeBPSrequiredstring
gasPricerequiredstring
feeCommitmentrequiredobject
expirationrequirednumber
assetrequiredstring
withdrawalDatarequiredstring
signedRelayerCommitmentrequiredstring
extraGasrequiredboolean
amountrequiredstring
detailrequiredobject
relayTxCostrequiredobject
gasrequiredstring
ethrequiredstring
extraGasFundAmountobject
gasrequiredstring
ethrequiredstring
extraGasTxCostobject
gasrequiredstring
ethrequiredstring
json
{
  "baseFeeBPS": "string",
  "feeBPS": "string",
  "gasPrice": "string",
  "feeCommitment": {
    "expiration": 0,
    "asset": "string",
    "withdrawalData": "string",
    "signedRelayerCommitment": "string",
    "extraGas": true,
    "amount": "string"
  },
  "detail": {
    "relayTxCost": {
      "gas": "string",
      "eth": "string"
    },
    "extraGasFundAmount": {
      "gas": "string",
      "eth": "string"
    },
    "extraGasTxCost": {
      "gas": "string",
      "eth": "string"
    }
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "chainId": 0,
  "amount": "",
  "asset": "",
  "recipient": "",
  "extraGas": true
}' \
  "https://api-stg.clkd.xyz/relayer/quote"

Relayer request

POST/relayer/request

Submit a privacy pool withdrawal for relay

Request Body
withdrawalrequiredobject
processooorrequiredstring
datarequiredstring
proofrequiredobject
pi_arequiredstring[]
pi_brequiredarray[]
pi_crequiredstring[]
protocolrequired"groth16"
curverequired"bn128"
publicSignalsrequiredstring[]
scoperequiredstring
chainIdrequirednumber
feeCommitmentrequiredobject
expirationrequirednumber
assetrequiredstring
withdrawalDatarequiredstring
signedRelayerCommitmentrequiredstring
extraGasrequiredboolean
amountrequiredstring
Responses
200Default Response
Schema
successrequiredboolean
txHashstring
errorstring
timestamprequirednumber
requestIdrequiredstring
json
{
  "success": true,
  "txHash": "string",
  "error": "string",
  "timestamp": 0,
  "requestId": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
500Default Response
Schema
errorrequiredstring
messagerequiredstring
json
{
  "error": "string",
  "message": "string"
}
503Default Response
Schema
errorrequiredstring
e.g. "Service Unavailable"
messagerequiredstring
codestring
Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.
json
{
  "error": "Service Unavailable",
  "message": "string",
  "code": "SERVER_BUSY"
}
Try it
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "withdrawal": {
    "processooor": "",
    "data": ""
  },
  "proof": {
    "pi_a": [
      ""
    ],
    "pi_b": [
      [
        ""
      ]
    ],
    "pi_c": [
      ""
    ],
    "protocol": "",
    "curve": ""
  },
  "publicSignals": [
    ""
  ],
  "scope": "",
  "chainId": 0,
  "feeCommitment": {
    "expiration": 0,
    "asset": "",
    "withdrawalData": "",
    "signedRelayerCommitment": "",
    "extraGas": true,
    "amount": ""
  }
}' \
  "https://api-stg.clkd.xyz/relayer/request"

Send

Resolve send destination avatar

GET/v1/accounts/{accountId}/destination-avatar🔒

Resolve the public ENS avatar URL for a send destination. Returns null when the destination is not an ENS name or no public avatar is configured.

Parameters
NameInTypeDescription
destinationAddress*querystringDestination address or ENS name entered in the send form.
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
avatarUrlrequiredstring | null
json
{
  "avatarUrl": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
Query Parameters
destinationAddress
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/destination-avatar"

Classify send recipient address

GET/v1/accounts/{accountId}/recipient-address-kind🔒

Classify a send recipient address as an EOA, EIP-7702 delegated EOA, or contract on the selected chain.

Parameters
NameInTypeDescription
chainId*querynumberChain ID selected in the send form.
address*querystringRaw 0x recipient address to inspect.
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
kindrequired"eoa" | "eip7702" | "contract"
json
{
  "kind": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
502Default Response
Schema
errorrequiredstring
e.g. "Bad Gateway"
messagerequiredstring
codestring
e.g. "SWAP_UNAVAILABLE"
json
{
  "error": "Bad Gateway",
  "message": "string",
  "code": "SWAP_UNAVAILABLE"
}
Try it
Path Parameters
accountId
Query Parameters
chainId
address
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/recipient-address-kind"

Account

Get contact email

GET/v1/accounts/{accountId}/contact-email🔒

Return the account's optional contact email, or null if none is set.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
emailrequiredstring | null
json
{
  "email": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/contact-email"

Set contact email

PUT/v1/accounts/{accountId}/contact-email🔒

Set or replace the account's optional contact email. Used for account updates, product news, and support/feedback outreach.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Request Body
emailrequiredstring
Optional contact email for the account.
Responses
200Default Response
Schema
emailrequiredstring | null
json
{
  "email": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
Request Body
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
  "email": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/contact-email"

Delete contact email

DELETE/v1/accounts/{accountId}/contact-email🔒

Remove the account's contact email. Idempotent.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
emailrequiredstring | null
json
{
  "email": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X DELETE \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/contact-email"

Dismiss profile prompt

PUT/v1/accounts/{accountId}/profile-prompts/{promptId}/dismissal🔒

Permanently dismiss an allowed profile prompt for this account across browsers and devices. Idempotent.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
promptId*pathstringA profile prompt that supports permanent dismissal.
Responses
200Default Response
Schema
promptIdrequired"custom-ens"
dismissedAtrequiredstring (date-time)
json
{
  "promptId": "string",
  "dismissedAt": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
promptId
curl -X PUT \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/profile-prompts/{promptId}/dismissal"

Get address book

GET/v1/accounts/{accountId}/address-book🔒

List the account's saved contacts, most recently used first.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
Responses
200Default Response
Schema
entriesrequiredobject[]
addressrequiredstring
EIP-55 checksummed contact address.
namerequiredstring
Display name for the saved contact.
lastUsedAtrequiredstring | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
json
{
  "entries": [
    {
      "address": "string",
      "name": "string",
      "lastUsedAt": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/address-book"

Get address book address ownership

GET/v1/accounts/{accountId}/address-book/ownership/{address}🔒

Check whether an address belongs to the current Cloaked account.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
address*pathstring—
Responses
200Default Response
Schema
isOwnAddressrequiredboolean
json
{
  "isOwnAddress": true
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
address
curl -X GET \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/address-book/ownership/{address}"

Upsert address book entry

PUT/v1/accounts/{accountId}/address-book/{address}🔒

Save or rename a contact. The address is normalized to EIP-55 checksummed form. Requires a member spend-key signature over the canonical save-contact message.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
address*pathstring—
Request Body
namerequiredstring
Display name for the saved contact.
signaturerequiredstring
Member spend-key signature over the canonical save-contact message (personal_sign).
issuedAtrequiredstring
ISO-8601 timestamp embedded in the signed message. Signatures expire 10 minutes after issuedAt; timestamps up to 60 seconds ahead of server time are accepted for clock skew.
Responses
200Default Response
Schema
entryrequiredobject
addressrequiredstring
EIP-55 checksummed contact address.
namerequiredstring
Display name for the saved contact.
lastUsedAtrequiredstring | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
json
{
  "entry": {
    "address": "string",
    "name": "string",
    "lastUsedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
address
Request Body
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
  "name": "",
  "signature": "",
  "issuedAt": ""
}' \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/address-book/{address}"

Delete address book entry

DELETE/v1/accounts/{accountId}/address-book/{address}🔒

Remove a saved contact. Idempotent.

Parameters
NameInTypeDescription
accountId*pathstring (uuid)Account ID
address*pathstring—
Responses
200Default Response
Schema
deletedrequiredboolean
json
{
  "deleted": true
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
401Default Response
Schema
errorrequiredstring
e.g. "Unauthorized"
messagerequiredstring
codestring
e.g. "UNAUTHORIZED"
json
{
  "error": "Unauthorized",
  "message": "string",
  "code": "UNAUTHORIZED"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 60 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 60 requests per 1 minute."
}
Try it
Path Parameters
accountId
address
curl -X DELETE \
  "https://api-stg.clkd.xyz/v1/accounts/{accountId}/address-book/{address}"

Simulation

Simulate transaction

POST/v1/simulate🔒

Simulate a transaction to preview asset changes before signing.

Request Body
Variant 1
chainIdrequirednumber
Chain ID
fromrequiredstring
Sender address
torequiredstring
Target address
valuerequiredstring
Value in wei (decimal string)
datarequiredstring
Calldata (hex string)
Variant 2
chainIdrequirednumber
Chain ID
fromrequiredstring
Sender address
callsrequiredobject[]
Calls to execute consecutively against shared simulation state
torequiredstring
Target address
valuerequiredstring
Value in wei (decimal string)
datarequiredstring
Calldata (hex string)
Variant 3
chainIdrequirednumber
Chain ID
transactionsrequiredobject[]
Ordered calls from every signer in an exact product quote
fromrequiredstring
Sender address
intentIndexrequiredinteger
Signed intent position
callIndexrequiredinteger
Call position within the intent
torequiredstring
Target address
valuerequiredstring
Value in wei (decimal string)
datarequiredstring
Calldata (hex string)
Responses
200Default Response
Schema
successrequiredboolean
providerrequired"local" | "tenderly"
gasUsednumber
failureReason"insufficient-token-balance" | "reverted" | "unavailable"
assetChangesCompleterequiredboolean
assetChangesrequiredobject[]
intentIndexinteger
callIndexinteger
typerequired"transfer" | "approval" | "native"
tokenobject
addressrequiredstring
symbolstring
decimalsinteger
namestring
fromrequiredstring
torequiredstring
amountrequiredstring
rawAmountrequiredstring
errorstring
json
{
  "success": true,
  "provider": "string",
  "gasUsed": 0,
  "failureReason": "string",
  "assetChangesComplete": true,
  "assetChanges": [
    {
      "intentIndex": null,
      "callIndex": null,
      "type": "string",
      "token": {
        "address": "string",
        "symbol": "string",
        "decimals": null,
        "name": "string"
      },
      "from": "string",
      "to": "string",
      "amount": "string",
      "rawAmount": "string"
    }
  ],
  "error": "string"
}
400Default Response
Schema
errorrequiredstring
e.g. "Bad request"
messagerequiredstring
codestring
e.g. "BAD_REQUEST"
availablestring
Available balance in smallest unit (for INSUFFICIENT_BALANCE)
tokenSymbolstring
Token symbol for the balance that caused the quote error
tokenAddressstring
Token address for the balance that caused the quote error
tokenDecimalsnumber
Token decimals for smallest-unit quote error amounts
minAmountstring
Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)
maxSendablestring
Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.
feeEstimatestring
Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)
requiredstring
Requested amount plus estimated fee in smallest unit
shortfallstring
Amount by which the request exceeds the fee-adjusted maximum
spendableCountnumber
Spendable count used for the fee-adjusted maximum
maxInputsnumber
Maximum input count allowed by the selector
selectedAmountstring
Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)
relayFeestring
Estimated relay fee for the selected withdrawal balances
feeLimitstring
Maximum relay fee allowed for the requested withdrawal amount
maxRelayFeeBPSnumber
Maximum relay fee basis points allowed by the pool
requiredRelayFeeBPSstring
Required relay fee basis points for the requested withdrawal
selectedCountnumber
Number of selected pool balances considered by the quote
resolvedAddressstring
Exact resolved destination address requiring acknowledgement for a contract recipient
json
{
  "error": "Bad request",
  "message": "string",
  "code": "BAD_REQUEST",
  "available": "0",
  "tokenSymbol": "ETH",
  "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenDecimals": 18,
  "minAmount": "0.00036 ETH",
  "maxSendable": "0.018 ETH",
  "feeEstimate": "1000000000000000",
  "required": "1010000000000000000",
  "shortfall": "1000000000000000",
  "spendableCount": 1,
  "maxInputs": 50,
  "selectedAmount": "0.02 ETH",
  "relayFee": "0.0042 ETH",
  "feeLimit": "0.001 ETH",
  "maxRelayFeeBPS": 1000,
  "requiredRelayFeeBPS": "1523",
  "selectedCount": 2,
  "resolvedAddress": "string"
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
Try it
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "chainId": 0,
  "from": "",
  "to": "",
  "value": "",
  "data": ""
}' \
  "https://api-stg.clkd.xyz/v1/simulate"

Utilities

Lookup function signatures

POST/v1/function-signatures🔒

Batch-resolve 4-byte function selectors to human-readable signatures. Uses a server-side cache backed by Sourcify's 4byte signature database.

Request Body
selectorsrequiredstring[]
Array of 4-byte hex selectors (e.g. ["0xa9059cbb"])
Responses
200Default Response
Schema
signaturesrequiredobject
Map of selector → signature (null if unknown or ambiguous)
candidatesrequiredobject
Map of selector → bounded candidate set for safe client-side calldata decoding
json
{
  "signatures": null,
  "candidates": null
}
403Default Response
Schema
errorrequiredstring
e.g. "Forbidden"
messagerequiredstring
json
{
  "error": "Forbidden",
  "message": "string"
}
Try it
Request Body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "selectors": [
    ""
  ]
}' \
  "https://api-stg.clkd.xyz/v1/function-signatures"

Get clear signing descriptor

GET/v1/clear-signing/descriptor

Resolve an ERC-7730 descriptor from Cloaked’s pinned, validated registry snapshot for a specific chain, contract, and calldata or EIP-712 format.

Parameters
NameInTypeDescription
chainId*queryinteger—
address*querystring—
kind*queryany—
callerquerystring—
selectorquerystring—
formatKeyquerystring—
Responses
200Default Response
Schema
kindrequired"calldata" | "eip712"
descriptorrequiredobject
sourcerequiredobject
registryrequired"ethereum" | "cloaked"
statusrequired"official" | "pending-review"
repositoryrequiredstring
commitrequiredstring
pathrequiredstring
urlrequiredstring (uri)
descriptorHashrequiredstring
pullRequeststring (uri)
bindingobject | object
json
{
  "kind": "string",
  "descriptor": null,
  "source": {
    "registry": "string",
    "status": "string",
    "repository": "string",
    "commit": "string",
    "path": "string",
    "url": "string",
    "descriptorHash": "string",
    "pullRequest": "string"
  },
  "binding": {
    "kind": "string",
    "standard": "string",
    "chainId": null,
    "address": "string",
    "evidence": {
      "kind": "string",
      "onchainDecimals": null,
      "catalogSources": [
        "string"
      ]
    }
  }
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 120 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 120 requests per 1 minute."
}
502Default Response
Schema
errorrequiredstring
e.g. "Bad Gateway"
messagerequiredstring
codestring
e.g. "SWAP_UNAVAILABLE"
json
{
  "error": "Bad Gateway",
  "message": "string",
  "code": "SWAP_UNAVAILABLE"
}
Try it
Query Parameters
chainId
address
kind
caller
selector
formatKey
curl -X GET \
  "https://api-stg.clkd.xyz/v1/clear-signing/descriptor"

Get sourcify function

GET/v1/clear-signing/sourcify-function

Resolve the exact ABI function from source Sourcify matched to the current direct-contract runtime or a freshly proven proxy implementation.

Parameters
NameInTypeDescription
chainId*queryinteger—
address*querystring—
callerquerystring—
selector*querystring—
Responses
200Default Response
Schema
Variant 1
evidenceVersionrequired1
chainIdrequiredinteger
addressrequiredstring
selectorrequiredstring
contractKindrequired"direct"
functionDeclarationrequiredstring
functionHashrequiredstring
runtimeCodeHashrequiredstring
matchrequired"match" | "exact_match"
runtimeMatchrequired"match" | "exact_match"
sourceUrlrequiredstring (uri)
Variant 2
evidenceVersionrequired2
chainIdrequiredinteger
addressrequiredstring
callerrequiredstring
selectorrequiredstring
contractKindrequired"proxy"
proxyKindrequired"eip1967" | "beacon" | "safe"
proxyCodeHashrequiredstring
implementationAddressrequiredstring
implementationCodeHashrequiredstring
beaconAddressstring
beaconCodeHashstring
blockNumberrequiredstring
blockHashrequiredstring
functionDeclarationrequiredstring
functionHashrequiredstring
matchrequired"match" | "exact_match"
runtimeMatchrequired"match" | "exact_match"
sourceUrlrequiredstring (uri)
json
{
  "evidenceVersion": 0,
  "chainId": null,
  "address": "string",
  "selector": "string",
  "contractKind": "string",
  "functionDeclaration": "string",
  "functionHash": "string",
  "runtimeCodeHash": "string",
  "match": "string",
  "runtimeMatch": "string",
  "sourceUrl": "string"
}
404Default Response
Schema
errorrequiredstring
e.g. "Not found"
messagerequiredstring
json
{
  "error": "Not found",
  "message": "string"
}
429Default Response
Schema
errorrequiredstring
e.g. "Too Many Requests"
messagerequiredstring
e.g. "Rate limit exceeded. Maximum 120 requests per 1 minute."
json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 120 requests per 1 minute."
}
502Default Response
Schema
errorrequiredstring
e.g. "Bad Gateway"
messagerequiredstring
codestring
e.g. "SWAP_UNAVAILABLE"
json
{
  "error": "Bad Gateway",
  "message": "string",
  "code": "SWAP_UNAVAILABLE"
}
Try it
Query Parameters
chainId
address
caller
selector
curl -X GET \
  "https://api-stg.clkd.xyz/v1/clear-signing/sourcify-function"