Python SDK

Server-side SDK for integrating Dfns into Python backends

Attention: This project is currently in BETA.

This means that while we’ve worked hard to ensure its functionality, stability, and security, there may still be bugs, performance issues, or unexpected behavior.

The Python SDK is designed for server-side/backend applications. It handles request signing and provides typed access to the Dfns API.

You can find the repository here.

Installation

pip install dfns_sdk

Quick start

1. Read-only operations

For read-only operations (listing wallets, fetching balances, etc.), you only need an auth token:

from dfns_sdk import DfnsClient, DfnsClientConfig

config = DfnsClientConfig(auth_token="your-auth-token")

with DfnsClient(config) as client:
    wallets = client.wallets.list_wallets()
    for wallet in wallets["items"]:
        print(f"{wallet['id']}: {wallet['network']} {wallet['address']}")

For a quick test you can get your login token (short-lived) from the Dfns Dashboard under Settings > Personal Access Tokens.

2. Signing requests

State-changing operations (creating wallets, signing transactions, etc.) require cryptographic request signing. Choose your approach based on where the private key lives:

Direct signing

Use DfnsClient with a KeySigner when your backend has direct access to the private key (e.g., stored in a file or environment variable).

This is ideal for service accounts where the private key is securely stored on your server.

from dfns_sdk import DfnsClient, DfnsClientConfig, KeySigner

signer = KeySigner(
    credential_id="cr-...",
    private_key=open("/path/to/private-key.pem").read(),
    app_origin="https://your-app.example.com"
)

config = DfnsClientConfig(
    auth_token="your-auth-token",
    signer=signer
)

with DfnsClient(config) as client:
    wallet = client.wallets.create_wallet({"network": "EthereumSepolia"})
    print(f"Created wallet: {wallet['id']}")

Delegated signing

Use DfnsDelegatedClient when the private key is not directly accessible to your backend:

• User passkeys: Users sign with their own device (WebAuthn/biometrics)
• External KMS: Private key stored in AWS KMS, HashiCorp Vault, etc.

The flow splits into init and complete phases:

from dfns_sdk import DfnsDelegatedClient, DfnsDelegatedClientConfig

config = DfnsDelegatedClientConfig(auth_token="user-auth-token")

with DfnsDelegatedClient(config) as client:
    # Step 1: Initialize and get a challenge
    challenge = client.wallets.create_wallet_init(body={"network": "EthereumSepolia"})

    # Step 2: Send challenge to be signed externally
    # - For passkeys: send to user's frontend for WebAuthn signing
    # - For KMS: send to your KMS to sign
    # signed_challenge = ... (received from external signer)

    # Step 3: Complete with the signed challenge
    wallet = client.wallets.create_wallet_complete(
        body={"network": "EthereumSepolia"},
        signed_challenge={
            "challengeIdentifier": challenge["challengeIdentifier"],
            "firstFactor": signed_challenge
        }
    )
    print(f"Created wallet: {wallet['id']}")

Next steps

• Create a service account for server-to-server authentication with long-lived tokens
• Development guide for detailed request signing architecture
• Delegated wallets for implementing user passkey flows
• End-user authentication for building user-facing applications