Skip to main content
The release notes for our Java SDK.
​

​
Added

  • Add HD wallet derivation: WalletCreateRequestBody.derivation() derives a new wallet from an existing HD root wallet, and Wallet.parentWalletId() returns the root wallet’s ID.
  • Add TransferRequestBody.custodyOptions() to pass payment initiation and Strong Customer Authentication (SCA) context for custodial wallet transfers.
  • Add developerFeePercent to CreatePayoutRequestBody, BridgeCreateFiatDepositAccountRequestBody, PayoutResponse, and BridgeFiatDepositAccount.
  • Add PayoutDestination.paymentRail() to choose the fiat payment rail for a payout.
  • Add BridgeCreateExternalFiatAccountRequestBody.accountOwner(), required for iban, gb, and swift accounts.
  • Add the SolanaInstructionDataCondition policy condition, which matches Solana instruction arguments and accounts using an inline Anchor IDL.
  • Add FundsDepositedWebhookPayload.depositMetadata() to identify refunded deposits.
  • Add the TempoZoneSettlementWalletActionStep wallet action step.
  • Add User.frozenAt(), KyxEndorsement.issues(), and CustodianTransactionWalletActionStep.transactionHash().

​
Breaking changes

Model constructor parameter orderPublic constructors on model classes (io.privy.api.models.*) now take their parameters in alphabetical order by field name. This is a one-time change caused by moving the SDK to a new source OpenAPI spec. Builders, getters, with* methods, SDK service methods, and the JSON wire format are unchanged. Apps that create models with Model.builder() are not affected.Apps that call model constructors positionally should switch to Model.builder(). Most of those calls fail to compile, so the compiler points to each one. A few still compile because the reordered parameters share a type, and assign values to the wrong fields. For example, new NamedTokenTransferSource("base", "usdc") now sets asset to "base" and chain to "usdc".Check any positional calls to the following classes. The request models UserOperationInput, NamedTokenTransferSource, CustomTokenTransferSource, ExternalFiatAccountAddress, SparkTransferTokensRpcInputParams, and TronRawDataForSign are the most likely to appear in app code. In TronRawDataForSign, timestamp and expiration swap places.
  • AuthorizationKey, CustomTokenTransferSource, DepositCompletedDestination, EarnIncetiveClaimRewardEntry, EthereumSendCallsRpcResponseData, EthereumSendTransactionRpcResponseData, ExternalFiatAccountAddress, FailureReason, Gas, IntentExecutedWebhookPayloadBaseActionResult, IntentFailedWebhookPayloadBaseActionResult, KeyQuorumIntentResponseBaseActionResult, KyxCapabilities, KyxTosStatusDetail, LinkedAccountCustomOauth, NamedTokenTransferSource, OrganizationCreateRequestBody, OrganizationUpdateRequestBody, PayoutSource, PolicyIntentResponseBaseActionResult, PrivateKeyExportWebhookPayload, RpcIntentResponseBaseActionResult, RuleDeleteIntentResponseBaseActionResult, RuleIntentResponseBaseActionResult, RuleMutateIntentResponseBaseActionResult, SolanaSignAndSendTransactionRpcResponseData, SparkCreateLightningInvoiceRpcInputParams, SparkLightningReceiveRequest, SparkTransferLeaf, SparkTransferTokensRpcInputParams, TempoCall, TransferIntentResponseBaseActionResult, TronRawDataForSend, TronRawDataForSign, TronSendTransactionRpcResponseData, UserOperationInput, WalletFundsNativeTokenAsset, WalletIntentResponseBaseActionResult, WalletRecoveredWebhookPayload, and YieldClaimReward.
toString() output now lists fields in the same alphabetical order.Other changes
  • UsageCrossChainFeeRecordedWebhookPayload renamed to UsageSwapProviderFeeRecordedWebhookPayload, matching the usage.swap_provider_fee.recorded webhook event.
  • UsageCrossChainFeeRecordedResponse renamed to UsageSwapProviderFeeRecordedResponse.
  • developerFeePercent is now required when building PayoutResponse and BridgeFiatDepositAccount.
  • Constructors of Wallet, User, TransferRequestBody, WalletCreateRequestBody, KyxEndorsement, FundsDepositedWebhookPayload, CustodianTransactionWalletActionStep, BridgeCreateExternalFiatAccountRequestBody, BridgeCreateFiatDepositAccountRequestBody, BridgeFiatDepositAccount, and PayoutResponse take the new fields listed above. Builders are not affected.
​

​
Added

  • Add organization CRUD endpoints.
  • Add organization KYB endpoints.
  • Add organization external fiat account endpoints.
  • Add fiat deposit account endpoints.
  • Add the fiat payout endpoint with authorization signature support.
  • Add CONTAINS, STARTS_WITH, and ENDS_WITH operators to ConditionOperator for policy conditions.
  • Add XRPL chain support via WalletChainType and CurveSigningChainType.

​
Breaking changes

  • WithEncryption renamed to EncryptedWalletAuthenticateResponse in WalletAuthenticateWithJwtResponse oneOf factory methods.
  • WithoutEncryption renamed to RawWalletAuthenticateResponse.
  • AccessList renamed to AccessListEntry.
  • EntrypointVersion renamed to EVMUserOperationEntrypointVersion.
  • TransactionStatus renamed to BlockchainTransactionStatus.
  • LinkedAccountBaseWalletChainType renamed to FirstClassChainType.
  • CredentialDeviceType renamed to LinkedAccountPasskeyCredentialDeviceType.
  • APIException.bodyAsString() return type changed from String to Optional<String>. Use .orElse(e.getMessage()) to fall back to the error message.
  • APIException.body() return type changed from byte[] to Optional<byte[]>.
​

​
Added

  • Add support for POST /v1/wallets/authenticate/intents endpoint.
  • Add intent-bound signing key exchange utility.
​

​
Fixed

  • Fix deleteRule intent response deserialization.
​

​
Added

  • Intent authorization via JWT exchange endpoint (intents/authorize).
  • authorizeIntent convenience wrapper on PrivyIntentsService.
​

​
Added

  • PrivyIntentsService with request expiry support, wired into PrivyClient.
  • Intents API endpoints for eth_signUserOperation and other intent types.
  • Expose JwtExchange via privyClient.utils().

​
Breaking changes

  • Rename exchangeJwtForAuthorizationKey to exchangeJwtForUserSigningKey.
​

​
Added

  • AuthorizationSigner functional interface for external signing via KMS, HSM, or hardware wallets. Use AuthorizationContext.addSigner() or AuthorizationContext.withSigner() to register signers.
  • New signTransaction and sendTransaction overloads on PrivyEthereumService that accept UnsignedEthereumTransaction (union of standard and Tempo transactions). Existing overloads for UnsignedStandardEthereumTransaction are preserved for backward compatibility.
  • Spark Protocol support (Bitcoin/Lightning L2) with ~65 new classes including SparkNetwork, SparkBalance, lightning invoice support, and RPC methods.
  • Intent system with IntentType, IntentAuthorization, and intent lifecycle webhook payloads.
  • Wallet action webhooks for transfer, swap, earn deposit, earn incentive claim, earn withdraw lifecycles, and yield webhooks.
  • Tempo transaction (type 118) support with UnsignedTempoTransaction, TempoCall, TempoAAAuthorization, and TempoFeePayerSignature.
  • AccessList type for Ethereum access lists.
  • EthereumSendCallsCall, EthereumSendCallsRpcInput, and EthereumSendCallsRpcResponse for batched calls.
  • Export RPC methods: ExportPrivateKeyRpcInput/Response and ExportSeedPhraseRpcInput/Response.
  • New RawSignInput, RawSignInputParams, RawSignBytesParams, RawSignHashParams types replacing the deleted RawSignRequest/RawSignRequestParams.
  • ABI and smart contract types: AbiParameter, AbiSchema, EthereumTypedDataInput, TypedData.
  • Wallet action step types: WalletActionStep, WalletActionType, and chain-specific variants.
  • Wallet asset types: WalletAsset, WalletEthereumAsset, WalletSolanaAsset.
  • New fields: referenceId and experimentalDataSuffix on EthereumSendTransactionRpcInput; walletId on EthereumPersonalSignRpcInput and EthereumSignTransactionRpcInput.

​
Breaking changes

Wallets
  • Wallets.update() now takes a single WalletUpdateRequest object instead of multi-parameter overloads.
  • Wallets.export() now takes a single WalletExportRequest object instead of multi-parameter overloads.
  • WalletUpdateRequest.requestBody() renamed to walletUpdateRequestBody().
  • WalletUpdateRequestBody moved from operations to components package.
  • WalletUpdateRequestBody.additionalSigners() changed from List<WalletAdditionalSignerItem> to List<AdditionalSignerItemInput>.
  • Wallet.additionalSigners() changed from List<WalletAdditionalSigner> to List<WalletAdditionalSignerItem>.
  • WalletAdditionalSigner deleted, replaced by WalletAdditionalSignerItem.
  • UserOwner and PublicKeyOwner deleted, replaced by OwnerInputUser and OwnerInputPublicKey.
Wallet RPC
  • WalletRpcRequest.requestBody() renamed to walletRpcRequestBody().
  • WalletRpcResponse.oneOf() removed; use walletRpcResponse() returning Optional<WalletRpcResponse> from the components package.
  • WalletRpcRequestBody and WalletRpcResponseBody moved from operations to components package.
  • RawSignRequest and RawSignRequestParams (in operations) deleted, replaced by RawSignInput/RawSignInputParams in components.
  • Ethereum transaction field wrapper classes (e.g., EthereumSendTransactionRpcInputChainId, ...GasLimit, ...Value) removed and replaced with UnsignedStandardEthereumTransaction + Quantity.
  • EthereumSignTransactionRpcInputParams.transaction() and EthereumSendTransactionRpcInputParams.transaction() type changed from UnsignedStandardEthereumTransaction to UnsignedEthereumTransaction. Use UnsignedEthereumTransaction.of(transaction) to wrap existing instances.
Policies
  • Policies.update() now takes a single PolicyUpdateRequest object.
  • Policies.createRule() now takes a single CreateRuleRequest object.
  • Policies.deleteRule() now takes a single DeleteRuleRequest object.
  • PolicyCreateRequestBody.rules() now accepts List<Rule> instead of List<PolicyRuleRequestBody>.
  • PolicyChainType deleted, replaced by WalletChainType.
  • PolicyDeleteResponse.object() renamed to successResponse().
Key quorums
  • KeyQuorums.update() now takes a single KeyQuorumUpdateRequest object.
  • KeyQuorumCreateRequestBody and KeyQuorumUpdateRequestBody moved from operations to components package.
  • Builder methods renamed: .requestBody() to .keyQuorumCreateRequestBody() / .keyQuorumUpdateRequestBody().
Transactions
  • Transaction.status() changed from StatusEnum to TransactionStatus.
Webhooks
  • FundsDepositedWebhookPayload/FundsWithdrawnWebhookPayload asset sub-types consolidated into WalletFundsAsset union.
​

​
Changed

  • BREAKING: Status changed from an enum (BROADCASTED, CONFIRMED, etc.) to a oneOf union class (StatusOk | StatusDisabled | StatusClosed). This completely changes the Status type and its API surface.
  • BREAKING: Transaction.status() return type changed from Status (enum) to StatusEnum (new enum). The old Status type is now a different class entirely.
  • BREAKING: RawSignRequestParams changed from a concrete class with bytes(), encoding(), hashFunction() fields to a oneOf union of Hash | Bytes. The builder and all field accessors are removed.
  • BREAKING: RawSignRequestParamsUnion deleted; RawSignRequest.params() now returns RawSignRequestParams (which is the new oneOf type) instead of RawSignRequestParamsUnion.
  • BREAKING: UserLinkedAccountUnlinkRequestBody.type() changed from Type (deleted enum) to LinkedAccountType (new enum).
Field Type Changes on Linked Account Models
  • BREAKING: LinkedAccountCurveSigningEmbeddedWallet.recoveryMethod() changed from LinkedAccountCurveSigningEmbeddedWalletRecoveryMethod to EmbeddedWalletRecoveryMethod.
Constructor Signature Changes
  • BREAKING: WalletBalanceRequest constructor: asset and chain parameters changed from @Nonnull to @Nullable. The short-form constructor now only takes walletId. Return types of asset() and chain() changed from direct values to Optional<>.
  • BREAKING: RawSignResponse constructor now requires a method parameter (new required field).
  • Multiple linked account embedded wallet constructors now include imported and delegated as required boolean parameters instead of optional Boolean.
​

​
Changed

  • Better handling for parallel RPC requests
​

​
Changed

  • More debug logging
​

​
Changed

  • Use enhanced JSON mapper for authorization requests
​

​
Changed

  • Additional logging to help debug session expiration
​

​
Added

  • Passkey auth
  • Email auth
​

​
Added

  • System policies
  • Additional signer export
  • Policy APIs
  • Policy rule APIs
​
Initial release of the Java SDK. See the quickstart guide for more details on how to get started.