Request signing
All state-changing requests made to the Dfns API must be cryptographically signed. The SDK handles this automatically when you configure a signer.
For a detailed explanation of request signing and User Action Challenges, see Signing requests. Authentication tokens
The client requires a valid authToken. See Required headers for details on obtaining tokens.
KeySigner configuration
The KeySigner class provides factory methods for each supported key type. Each method takes a credential ID and the private key bytes:
import co.dfns.sdk.auth.*;
// Ed25519 — raw 32-byte seed
Signer signer = KeySigner.fromEd25519PrivateKey("cr-...", ed25519Seed);
// ECDSA P-256 — PKCS#8 DER encoded
Signer signer = KeySigner.fromEcdsaP256PrivateKey("cr-...", p256DerBytes);
// secp256k1 — raw 32-byte big-endian scalar
Signer signer = KeySigner.fromSecp256k1PrivateKey("cr-...", secp256k1Bytes);
// RSA — PKCS#8 DER encoded
Signer signer = KeySigner.fromRsaPrivateKey("cr-...", rsaDerBytes);
| Parameter | Description |
|---|
credentialId | ID of the credential registered with your token. Find it in the Dfns Dashboard under Settings > Service Accounts or Settings > Personal Access Tokens. |
privateKeyBytes | Private key bytes in the format expected by the factory method (see table below). |
| Factory method | Key format |
|---|
fromEd25519PrivateKey | Raw 32-byte seed |
fromEcdsaP256PrivateKey | PKCS#8 DER encoded |
fromSecp256k1PrivateKey | Raw 32-byte big-endian scalar |
fromRsaPrivateKey | PKCS#8 DER encoded |
If you have a PEM file, strip the header/footer lines and Base64-decode the content to get the DER bytes.
Sync vs async clients
The SDK provides both synchronous and asynchronous clients:
import co.dfns.sdk.*;
DfnsClientConfig config = DfnsClientConfig.builder()
.authToken("your-auth-token")
.signer(signer)
.build();
// Synchronous
try (DfnsClient client = new DfnsClient(config)) {
var wallets = client.wallets.listWallets(new co.dfns.sdk.wallets.model.ListWalletsQuery());
}
// Asynchronous — methods return CompletableFuture
try (DfnsAsyncClient asyncClient = new DfnsAsyncClient(config)) {
var walletsFuture = asyncClient.wallets.listWallets(new co.dfns.sdk.wallets.model.ListWalletsQuery());
var wallets = walletsFuture.join();
}
Available API domains
The client provides typed access to all Dfns API domains:
| Domain | Description |
|---|
client.wallets | Wallet creation, listing, and management |
client.keys | Key management operations |
client.policies | Policy rules and approvals |
client.permissions | Access control and permissions |
client.webhooks | Webhook configuration |
client.signers | Signer management |
client.staking | Staking operations |
client.networks | Network information |
client.exchanges | Exchange integrations |
client.feeSponsors | Fee sponsorship |
client.swaps | Token swap operations |
client.agreements | Agreement management |
client.allocations | Allocation management |
client.auth | Authentication helpers |
client.payouts | Payout operations |
Error handling
import co.dfns.sdk.*;
try {
var wallet = client.wallets.getWallet("invalid-wallet-id");
} catch (DfnsException e) {
System.out.printf("HTTP %d: %s (code: %s, requestId: %s)%n",
e.getHttpStatus(),
e.getErrorMessage(),
e.getDfnsErrorCode(),
e.getRequestId());
}
