> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Architecture and usage patterns for the Dfns Java SDK, including authentication, wallets, transfers, signing, and dependency setup.

## 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.

<Info>
  For a detailed explanation of request signing and User Action Challenges, see [Signing requests](/guides/developers/signing-requests).
</Info>

## Authentication tokens

The client requires a valid `authToken`. See [Required headers](/api-reference/auth) 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:

```java theme={null}
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            |

<Info>
  If you have a PEM file, strip the header/footer lines and Base64-decode the content to get the DER bytes.
</Info>

## Sync vs async clients

The SDK provides both synchronous and asynchronous clients:

```java theme={null}
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

```java theme={null}
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());
}
```