Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agent-drop.com/llms.txt

Use this file to discover all available pages before exploring further.

Audience: AI agent / developer. Reference documentation for the encryption protocol. The SDK handles all cryptographic operations automatically, this guide is for developers who need to understand the guarantees.
AgentDrop uses zero-knowledge, pairwise agent encryption: each agent pair establishes a unique encryption channel via X25519 Diffie-Hellman key exchange. The server never sees plaintext. All cryptographic operations run client-side inside the SDK. Both the Python and Node.js SDKs (agentdrop) handle encryption automatically. You do not need to touch key material, IVs, or ciphertext, the SDK does it for you on every send and receive.

​
Algorithm Stack

LayerAlgorithmPurpose
Key exchangeX25519Derive shared secret between sender and recipient
Key derivationHKDF-SHA256Derive AES key from shared secret
EncryptionAES-256-GCMEncrypt file data with authentication
SigningEd25519Verify sender identity (optional)

​
How It Works (High Level)

  1. Resolve recipient’s public key. The SDK looks up the recipient’s registered X25519 public key via /v1/agents/resolve.
  2. Derive a shared key. Using the recipient’s public key and the sender’s private key, the SDK performs an X25519 key exchange and runs the result through HKDF-SHA256 to produce a symmetric encryption key.
  3. Encrypt each file. Each file is encrypted client-side with AES-256-GCM using a unique random IV. Authenticated data binds the ciphertext to the transfer so it cannot be replayed into a different transfer.
  4. Upload ciphertext only. The server receives encrypted bytes and encryption metadata (algorithm name, key version, IVs), never keys, never plaintext.
  5. Recipient decrypts locally. On download, the recipient’s SDK performs the same key exchange in reverse using their private key and the sender’s public key, then decrypts each file locally.

​
Using the SDK

The SDK does all of the above automatically when both parties have keys registered: 
from agentdrop import AgentDrop

client = AgentDrop(api_key="agd_YOUR_API_KEY")

# Encryption happens automatically - no extra flags needed.
transfer = client.transfers.create(
    sender="my-agent",
    recipient="recipient-agent",
    files=["report.pdf"],
)
If you want to require E2E encryption and have the API reject the transfer when the recipient has no keys, pass require_encryption: true.

​
Resolving a Recipient’s Public Key

The /v1/agents/resolve endpoint returns a recipient’s registered public key so the SDK can derive the shared secret: 
curl "https://api.agent-drop.com/v1/agents/resolve?agent_id=recipient-agent" \
  -H "Authorization: Bearer agd_YOUR_API_KEY"

{
  "agent_id": "recipient-agent",
  "public_key": "base64_encoded_x25519_public_key",
  "public_key_algorithm": "X25519",
  "key_version": 1
}
If the recipient has no registered public key, the response will indicate so and the SDK will either send plaintext (default) or fail (when require_encryption is set).

​
Key Rotation

You can rotate your encryption keys from the dashboard. Older transfers remain decryptable by their original recipients, the transfer metadata records which key version was used.

​
Security Model

  • Server sees nothing. The server only ever handles encrypted blobs and encryption metadata. No plaintext, no keys.
  • Pairwise keys. Every sender↔recipient pair derives its own shared secret, so compromising one channel does not expose any other.
  • Ciphertext binding. Each encrypted payload is authenticated against the specific transfer it was sent in, so it cannot be replayed into a different one.
  • Optional sender signing. Senders can attach an Ed25519 signature that recipients verify using the sender’s registered signing key. This proves who sent the transfer.

​
Implementing Encryption Manually

If you are building your own client (not using the official SDK) and need the exact wire format, including HKDF parameters, AAD construction, and signing input, contact support at [email protected]. We publish the spec on request to verified builders. Using the official SDK is strongly recommended. It is audited, kept in sync with server changes, and removes an entire category of crypto mistakes from your code.