Rust SDK development

Request signing

All state-changing requests made to the DFNS API must be cryptographically signed. DfnsClient handles the challenge flow automatically when you configure a signer: it calls /auth/action/init, hands you the challenge, and replays your assertion on the real request.

For a detailed explanation of request signing and User Action Challenges, see Signing requests.

Client configuration

Both DfnsClient and DfnsDelegatedClient take the same Options:

use dfns_sdk_rust::{DfnsClient, Options};

let client = DfnsClient::new(Options {
    base_url: String::new(),
    auth_token: "your-auth-token".to_string(),
    signer: None,
    http: None,
})?;

Field	Description
`base_url`	DFNS API base URL. An empty string defaults to `https://api.dfns.io`.
`auth_token`	Service Account token, Personal Access Token, or user login token. See Required headers.
`signer`	`Option<Arc<dyn UserActionSigner>>`. Required for state-changing operations on `DfnsClient`, unused by `DfnsDelegatedClient`.
`http`	`Option<reqwest::Client>` to reuse your own HTTP client (connection pool, proxy, timeouts).

Implementing a signer

The SDK does not ship a key signer. It defines the UserActionSigner trait and leaves the credential-specific crypto to you, so the same client works with a raw key, an HSM, or a KMS:

use async_trait::async_trait;
use dfns_sdk_rust::error::Error;
use dfns_sdk_rust::signer::{
    CredentialAssertion, CredentialAssertionData, UserActionChallenge, UserActionSigner,
};

struct MyKeySigner {
    cred_id: String,
    // private key material, HSM handle, KMS client, ...
}

#[async_trait]
impl UserActionSigner for MyKeySigner {
    async fn sign(&self, challenge: &UserActionChallenge) -> Result<CredentialAssertion, Error> {
        // 1. Build the clientData JSON for `challenge.challenge` and base64url-encode it.
        // 2. Sign the clientData bytes with your credential's private key.
        // 3. Return the assertion, with the signature base64url-encoded.
        Ok(CredentialAssertion {
            kind: "Key".to_string(),
            credential_assertion: CredentialAssertionData {
                cred_id: self.cred_id.clone(),
                client_data: client_data_base64url,
                signature: signature_base64url,
            },
        })
    }
}

Field	Description
`kind`	`"Key"` for key credentials (Service Accounts, Personal Access Tokens), `"Fido2"` for passkeys.
`cred_id`	ID of the credential registered with your token. Find it in the DFNS Dashboard under `Settings` > `Service Accounts` or `Settings` > `Personal Access Tokens`.
`client_data`	Base64url-encoded `clientData` JSON built from the challenge.
`signature`	Base64url-encoded signature over the `clientData` bytes.

The exact clientData shape and stringification rules are defined in Credentials data. Incorrect stringification causes Unable to verify signature errors.

Calling a state-changing method without a configured signer returns Error::SignerRequired.

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 subscriptions
`client.signers`	Signer management
`client.staking`	Staking operations
`client.networks`	Network information
`client.exchanges`	Exchange integrations
`client.fee_sponsors`	Fee sponsorship
`client.swaps`	Token swap operations
`client.vaults`	Vault operations
`client.payins`	Payin operations
`client.payouts`	Payout operations
`client.allocations`	Allocation management
`client.address_watches`	Address watch operations
`client.agreements`	Agreement management
`client.auth`	Authentication and user management

Delegated signing

DfnsDelegatedClient exposes the same domains, but every operation that requires a user action signature is split into two methods:

Method	Returns
`<operation>_init(body)`	The `UserActionChallenge` to be signed by the end user
`<operation>_complete(body, challenge_identifier, assertion)`	The operation result

Read-only methods are identical on both clients. See Delegated wallets for a full implementation guide.

Error handling

All methods return Result<T, dfns_sdk_rust::Error>:

use dfns_sdk_rust::Error;

match client.wallets.get_wallet("invalid-wallet-id".to_string()).await {
    Ok(wallet) => println!("Wallet: {}", wallet.id),
    Err(Error::Api { status, body }) => {
        eprintln!("API error (status {}): {}", status, body.message);
    }
    Err(err) => eprintln!("Error: {}", err),
}

Variant	Cause
`Api { status, body }`	Non-2xx response with a decodable DFNS error body
`ApiRaw { status, raw }`	Non-2xx response with an undecodable body
`Config(String)`	Invalid base URL or auth token
`SignerRequired`	A signed operation was issued without a signer
`Signer(String)`	Your `UserActionSigner` implementation failed
`Transport(reqwest::Error)`	Connection, timeout, or other transport failure
`Serde(serde_json::Error)`	Request or response (de)serialization failure

Backend SDKs

Frontend SDKs

Request signing

Client configuration

Implementing a signer

Available API domains

Delegated signing

Error handling

​Request signing

​Client configuration

​Implementing a signer

​Available API domains

​Delegated signing

​Error handling

Request signing

Client configuration

Implementing a signer

Available API domains

Delegated signing

Error handling