Wallet Keys
Fetch the protectedSymmetricKey needed for wallet payouts.
POST /api/wallet/keys
Returns the selected wallet's walletId, protectedSymmetricKey and the owner's email. Use that wallet's key in transfers and payouts.
API payouts must be enabled on your account; ask support.
Create a wallet with the platform PIN
The account holder sets a six-digit PIN on the Hodle platform, then uses the same walletPin to create wallets through the API.
{
"network": "polygon",
"walletPin": "123456",
"protectedSymmetricKey": "<existing owner wallet protectedSymmetricKey>"
}protectedSymmetricKey optionally selects an existing owner wallet to verify the PIN. Omit it for automatic selection.
The response contains data.id, data.address, data.network, data.balance and the new wallet's data.protectedSymmetricKey. EVM responses also include data.chainId. Save the returned id as walletId. Each successful creation creates a new wallet, including successive calls for the same network; keep its ID instead of calling create again to retrieve it.
Creation supports polygon (default), base, bnb, solana and stellar. BNB Chain requires account enablement.
For a customer wallet, also pass its subAccountId. A reference subaccount inherits its owner's PIN; a legacy subaccount with its own user uses that user's PIN and email.
Give a subaccount wallet its own secret
Send pinScope: "WALLET" with subAccountId to protect the new wallet with a secret chosen by your customer instead of the platform PIN. The platform PIN is not required and cannot unlock this wallet, so only the holder of the secret can move its balance.
{
"subAccountId": "5d2b9e41-7c3a-4f18-a6e0-3b9c1d4e7f20",
"network": "base",
"pinScope": "WALLET",
"walletPin": "<customer secret, 6 to 512 characters>"
}walletPinmust be a random secret of at least 32 characters, such as one derived from a passkey (WebAuthn PRF). A six-digit PIN is accepted only where server-side PIN hardening is enabled for your account; otherwise the request answers400.- Transfers, payouts and swaps of this wallet take the same secret as
walletPin, with the wallet'sprotectedSymmetricKey. - Three invalid attempts lock only this wallet for 24 hours. The platform PIN and the other wallets are not affected.
- Available for
polygon,baseandbnb. Not available for legacy subaccounts with their own user. - Hodle never stores the secret, so it cannot be recovered. A lost secret means a lost wallet.
- Requires enablement; ask support (
403 WALLET_SCOPED_PIN_DISABLED).
Reference the new wallet
{ "walletId": "6a4d263d4cc67674bf72a3c9" }/api/wallet/keys accepts walletId alone for any wallet owned by your platform, including its subaccounts. You may also pass subAccountId to constrain the lookup to that subaccount.
Pass walletId, walletPin and the selected wallet's protectedSymmetricKey on transfers and payouts. For subaccount wallets, also send fromSubAccountId on transfers or subAccountId on payouts and other reads. The wallet must match the owner and scope.
Omit walletId for default selection.
For signature-based payouts, send walletId when preparing. The payoutIntentId binds the wallet; omit walletId when submitting the signature.
PIN format
Wallet creation requires exactly six digits. Use the same platform PIN to unlock the resulting wallet for transfers and payouts.
Rate limit
1 request per minute per API key and owner/subaccount scope. Different wallets in the same scope share the limit.
Request
The API key identifies the owner. Send walletId to select a wallet within your platform, or subAccountId to select a customer's default wallet. Both fields are also accepted as query parameters. If both are supplied, the wallet must belong to that subaccount. An empty body selects your main account's default wallet.
curl --request POST \
--url https://api.hodle.com.br/api/wallet/keys \
--header "Authorization: Bearer $API_KEY" \
--header "Accept: application/json"const res = await fetch('https://api.hodle.com.br/api/wallet/keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
Accept: 'application/json',
},
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/wallet/keys",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Accept": "application/json",
},
)
data = res.json()Response
{
"success": true,
"data": {
"walletId": "6a4d263d4cc67674bf72a3c9",
"protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4dpwHZA36dU9DiiZdDvQmNn...",
"email": "user@example.com"
}
}| Field | Type | Description |
|---|---|---|
data.walletId | string | ID of the wallet whose key is returned. |
data.protectedSymmetricKey | string | Pass this in POST /api/wallet/payout body. |
data.email | string | The user's email — keep alongside the key in your records. |
Errors
| Status | When |
|---|---|
400 | Invalid parameters. On creation: malformed PIN, no platform PIN established, or unsupported network. |
401 | Missing or invalid API key. |
403 | API payouts not enabled. On creation: wrong platform PIN, BNB Chain not enabled or production access not approved (BNB_FEATURE_DISABLED, BNB_PLANE_NOT_ACTIVE). |
404 | User, subaccount or wallet not found in your scope, or the wallet has no protected key. Select a protected wallet or contact support to recover funds. |
429 | Key retrieval rate limit (wait for Retry-After), or creation blocked for 24 hours after three wrong PINs. |
{ "success": false, "error": "Wallet has no protected symmetric key" }A subaccount you own that has no wallet yet answers 404 with errorCode: "SUBACCOUNT_WALLET_NOT_PROVISIONED". Subaccount wallets are created when its KYC is approved: wait for the KYC_APPROVED webhook (or GET /api/kyc?subAccountId=... with status: APPROVED) before reading it. An unknown subaccount keeps "Subaccount not found for this platform", without errorCode.
{
"success": false,
"error": "Sub-account has no wallet yet: wallets are created when its KYC is approved",
"errorCode": "SUBACCOUNT_WALLET_NOT_PROVISIONED"
}When to refetch
Cache the key and owner's email per walletId. Refetch when missing or after that wallet's protected key changes, such as a PIN reset. If a payout rejects the correct PIN, refresh the cached key.