DocsSecurity & Best Practices

Security & Best Practices

Advanced patterns for production-grade agent deployments. This section addresses real failure modes that emerge when autonomous AI agents control real money.

Handling Logic Loops (Idempotency)

The Risk

LLMs can hallucinate, get stuck in retry loops, or re-invoke the same tool call multiple times in a single reasoning chain. If your agent calls client.transfer() inside a loop without protection, a single bug could trigger 10, 50, or 100 duplicate payments — draining your wallet in seconds.

The Solution: Deterministic Idempotency Keys

Pass a deterministic idempotency_key to every transfer() call. Modexia's server deduplicates requests based on this key — if the same key is seen twice, the second request returns the original receipt without processing a new payment.

Best practice: Derive the key from the task context, for example hash(task_id + recipient + amount). This guarantees that even if the agent retries 50 times, Modexia only charges once.

python

import hashlib
from modexia import ModexiaClient

client = ModexiaClient(api_key="mx_test_...")

def pay_for_task(task_id: str, recipient: str, amount: float):
    """Idempotent payment — safe to retry any number of times."""

    # Deterministic key: same inputs always produce the same key
    raw = f"{task_id}:{recipient}:{amount}"
    idem_key = hashlib.sha256(raw.encode()).hexdigest()

    receipt = client.transfer(
        recipient=recipient,
        amount=amount,
        idempotency_key=idem_key,
        wait=True
    )
    return receipt

# Even if the LLM calls this 10 times with the same args,
# only 1 payment is processed on-chain
pay_for_task("task-99", "0xabc...", 5.0)
pay_for_task("task-99", "0xabc...", 5.0)  # returns cached receipt
pay_for_task("task-99", "0xabc...", 5.0)  # returns cached receipt

When to omit idempotency_key

If you omit the key, Modexia auto-generates a unique one per request. This is fine for one-shot payments. But for any agent running in a loop, retry chain, or multi-step reasoning flow, always pass an explicit deterministic key.

Phishing Defense (Vendor Allowlist)

The Risk

An autonomous agent browsing the web could encounter a malicious site that serves a fake HTTP 402 response with an inflated price and an attacker-controlled wallet address. If smart_fetch processes it without guardrails, the agent would unknowingly send funds to the attacker.

The Solution: Server-Side Policy Allowlist

Modexia's backend validates the destination address of every payment against your user-defined Policy Allowlist before signing the transaction. If the recipient is not on your approved list, the payment is rejected server-side — before it ever reaches the blockchain.

This is enforced at the Gateway layer, not in the SDK. Even if an attacker compromises your agent code, the server will block unauthorized destinations.

Configuring your allowlist

Set a spending policy with an explicit list of approved vendor addresses. Any payment to an address not on this list will be rejected with a 403.

bash

curl -X POST https://api.modexia.software/api/v1/agent/policy \
  -H "x-modexia-key: mx_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentAddress": "0xYourAgentWallet...",
    "dailyLimit": "50",
    "maxPerRequest": "5",
    "allowedRecipients": [
      "0xTrustedVendorA...",
      "0xTrustedVendorB...",
      "0xYourWorkerAgent..."
    ]
  }'

Defense in depth

Combine the allowlist with Spending Policies (maxPerRequest, dailyLimit) for defense in depth. Even if an allowed vendor is compromised, your agent cannot overspend beyond your configured limits.