Fluid Agentic DeFi Protocol (FADP/1.0): HTTP-Native Micropayment Authentication for Autonomous AI Agents

1.1. Design Goals

• HTTP-native: the entire payment handshake is expressed in standard HTTP status codes and header fields. No new transport layer is required.¶
• Stateless from the agent's perspective: the server supplies all information needed to pay in the 402 response; the agent needs no prior knowledge of the server's payment address or preferred token.¶
• Replay-safe: a nonce bound to each payment challenge ensures that a valid payment proof cannot be reused across requests or across sessions.¶
• Verifier-decoupled: servers can delegate on-chain verification to a third-party service, removing the need to run or maintain blockchain node infrastructure.¶
• Token- and chain-agnostic: while USDC on Base is the reference currency, FADP carries token and chain identifiers in every message and imposes no restriction on supported assets.¶
• Human-in-the-loop friendly: spending limits and out-of-band approval flows are outside protocol scope but are natural affordances of agent runtime environments built on FADP.¶

1.2. Non-Goals

• FADP does not specify how agents acquire, store, or rotate their wallet credentials.¶
• FADP does not define a streaming or subscription billing model. Each request-response pair is an independent payment event.¶
• FADP does not mandate a specific blockchain or token.¶
• FADP does not replace existing API authentication schemes; it may operate alongside them.¶

4.1. X-FADP-Required

The X-FADP-Required response header field is sent by the server in a 402 response. Its value is a JSON object with the following members:¶

version

REQUIRED. String. MUST be "1.0" for this version of the protocol.¶

amount

REQUIRED. String. The amount of the specified token that the agent MUST transfer, expressed as a decimal number (e.g., "0.001"). The server SHOULD use the minimal number of decimal places necessary to avoid ambiguity.¶

token

REQUIRED. String. The symbol of the digital asset to be transferred (e.g., "USDC", "ETH", "USDT"). The symbol SHOULD conform to the canonical symbol registered with the issuer or a well-known token list.¶

chain

REQUIRED. String. The identifier of the blockchain network on which the transfer must be executed. Registered values include "base" (Base Mainnet), "ethereum" (Ethereum Mainnet), and "solana" (Solana Mainnet). Implementors MAY define additional chain identifiers using reverse-DNS notation to avoid collision.¶

payTo

REQUIRED. String. The blockchain address of the server operator's wallet. For EVM-compatible chains, this MUST be a checksummed Ethereum address (EIP-55).¶

nonce

REQUIRED. String. A cryptographically random, single-use token generated by the server for this payment challenge. The server MUST ensure that each nonce is unique across all active challenges. The nonce MUST be at least 16 bytes of entropy, encoded as a lowercase hexadecimal string (minimum 32 characters).¶

expires

REQUIRED. Number. A Unix timestamp (seconds since epoch) indicating when this payment challenge expires. The server MUST reject proofs referencing a nonce whose expiry has passed. The RECOMMENDED default TTL is 300 seconds (5 minutes).¶

description

OPTIONAL. String. A human-readable description of the resource or service being paid for (e.g., "Premium market data API"). Intended for display in agent UIs and transaction logs.¶

verifyUrl

OPTIONAL. String. An HTTPS URL identifying the verification service the server will use to confirm payment proofs. If omitted, the default is https://fluidnative.com/v1/fadp/verify. Servers operating their own verification infrastructure SHOULD set this field.¶

Example value (formatted for readability; actual header value MUST be a single-line JSON string):¶

{
  "version": "1.0",
  "amount": "0.001",
  "token": "USDC",
  "chain": "base",
  "payTo": "0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234",
  "nonce": "a3f9c2b1d4e5f6a7b8c9d0e1f2a3b4c5",
  "expires": 1745001234,
  "description": "GPT-4o inference via OpenRouter proxy",
  "verifyUrl": "https://fluidnative.com/v1/fadp/verify"
}

4.2. X-FADP-Proof

The X-FADP-Proof request header field is sent by the agent in the authenticated request. Its value is a JSON object with the following members:¶

txHash

REQUIRED. String. The transaction hash of the on-chain transfer executed by the agent in response to the payment challenge. For EVM-compatible chains, this is a 0x-prefixed 32-byte hex string.¶

nonce

REQUIRED. String. The nonce value copied verbatim from the X-FADP-Required header of the payment challenge to which this proof responds. The server MUST verify that this nonce matches a known, unexpired, unconsumed challenge.¶

timestamp

REQUIRED. Number. A Unix timestamp (seconds since epoch) representing the time at which the agent assembled this proof. The server SHOULD reject proofs where |currentTime - timestamp| > 300 seconds.¶

agentKeyPrefix

OPTIONAL. String. A non-sensitive prefix of the agent's credential (e.g., the first 8 characters of a fwag_ key), used for logging and audit. Implementations MUST NOT include the full credential.¶

Example:¶

{
  "txHash": "0xabc1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
  "nonce": "a3f9c2b1d4e5f6a7b8c9d0e1f2a3b4c5",
  "timestamp": 1745001200,
  "agentKeyPrefix": "fwag_a3f9"
}

5.1. Verification Request

The server sends an HTTP POST to the verifyUrl with a JSON body containing:¶

txHash

REQUIRED. String. The transaction hash from the agent's proof.¶

payTo

REQUIRED. String. The wallet address that should have received the transfer.¶

amount

REQUIRED. String. The amount that should have been transferred.¶

token

REQUIRED. String. The token symbol.¶

chain

REQUIRED. String. The chain identifier.¶

nonce

REQUIRED. String. The nonce from the original challenge.¶

5.2. Verification Response

The verification service responds with a JSON object:¶

verified

REQUIRED. Boolean. true if and only if all of the following conditions hold:¶

• The transaction identified by txHash exists on the specified chain.¶
• The transaction status is finalized (not reverted).¶
• The recipient address matches payTo.¶
• The transferred amount is greater than or equal to the required amount.¶
• The transferred token matches the required token.¶

txHash

OPTIONAL. String. Echo of the verified transaction hash.¶

amount

OPTIONAL. String. The actual transferred amount.¶

token

OPTIONAL. String. The actual transferred token symbol.¶

chain

OPTIONAL. String. The chain on which the transfer occurred.¶

from

OPTIONAL. String. The sender's wallet address.¶

to

OPTIONAL. String. The recipient's wallet address (SHOULD match payTo).¶

error

OPTIONAL. String. A human-readable error message when verified is false.¶

Example successful response:¶

{
  "verified": true,
  "txHash": "0xabc123...",
  "amount": "0.001",
  "token": "USDC",
  "chain": "base",
  "from": "0xAgentWallet...",
  "to": "0xServerWallet..."
}

Example failed response:¶

{
  "verified": false,
  "error": "Transfer amount 0.0005 USDC is less than required 0.001 USDC"
}

6.1. Issuing Payment Challenges

When a server receives a request for a FADP-protected resource without an X-FADP-Proof header, it MUST:¶

1. Generate a nonce of at least 16 bytes of cryptographically secure random data.¶
2. Record the nonce and its expiry time in durable server-side storage (memory, cache, or database).¶
3. Respond with HTTP 402.¶
4. Set the X-FADP-Required header to a JSON object as defined in Section 4.1.¶
5. Set Access-Control-Expose-Headers: X-FADP-Required to ensure cross-origin agents can read the header.¶

6.2. Verifying Payment Proofs

When a server receives a request with an X-FADP-Proof header, it MUST perform the following checks in order, returning an appropriate error response if any check fails:¶

1. Parse the header value as JSON; return 400 if malformed.¶
2. Verify that txHash, nonce, and timestamp are present; return 400 if any is absent.¶
3. Look up the nonce in server-side storage; return 402 if the nonce is unknown.¶
4. Verify the nonce has not expired; return 402 if expired (delete the nonce).¶
5. Verify that |currentTime - proof.timestamp| <= 300 seconds; return 402 if outside range.¶
6. Call the verification service at verifyUrl; return 402 if verified is false.¶
7. Atomically mark the nonce as consumed (delete it from storage) to prevent replay.¶
8. Proceed to handle the original request.¶

Step 7 (nonce consumption) MUST occur before the server fulfills the request. If the server cannot atomically consume the nonce and fulfill the request (e.g., due to a crash), it SHOULD err on the side of not consuming the nonce, accepting the risk of a duplicate fulfillment rather than silently accepting payment without delivering service.¶

10.1. Replay Attacks

The nonce mechanism is the primary defense against replay attacks. A valid txHash from a past payment cannot be reused because:¶

1. Each payment challenge carries a unique nonce.¶
2. The proof MUST echo that nonce.¶
3. The server atomically consumes the nonce upon first successful verification.¶
4. Subsequent proofs referencing the same nonce are rejected with 403.¶

Server implementations MUST use cryptographically secure random number generation for nonces (e.g., /dev/urandom or equivalent). Predictable nonces would allow an attacker to pre-compute valid proofs.¶

The nonce store MUST be shared across all instances of a horizontally scaled server deployment. If a local per-process nonce store is used, the same nonce could be accepted by two different instances simultaneously, creating a replay window. A distributed cache (e.g., Redis) or a database with atomic compare-and-delete operations is RECOMMENDED for production deployments.¶

10.2. Overpayment

The verification service checks that the transferred amount is at least the required amount. Servers SHOULD NOT issue refunds for overpayments, as the complexity of doing so on-chain outweighs the benefit for small amounts. Agents SHOULD transfer exactly the required amount to avoid unnecessary token loss.¶

10.3. Front-Running and Transaction Interception

In principle, an attacker observing the agent's on-chain transaction in the mempool could copy the txHash and attempt to submit a proof before the legitimate agent. This attack is mitigated by:¶

1. The nonce binding: the attacker must have obtained the nonce from a legitimate 402 challenge targeted at their own session. Nonces are per-session and cannot be forged.¶
2. The proof timestamp check: the server rejects proofs assembled more than 300 seconds after the challenge was issued.¶

Servers that require strong session binding MAY add an additional check verifying that the HTTP session initiating the proof matches the session that triggered the original challenge (e.g., via a session cookie or TLS channel binding), though this is outside the scope of the current protocol version.¶

10.4. Verification Service Trust

Servers that delegate verification to a third-party service are implicitly trusting that service's honesty and availability. A compromised or malicious verification service could return verified: true for invalid proofs, allowing unauthorized access.¶

Servers operating in high-value contexts SHOULD run their own verification infrastructure against a direct blockchain RPC endpoint. The verification endpoint API defined in Section 5 is designed to be self-hostable for this reason.¶

10.5. Blockchain Finality

On chains with probabilistic finality (including Ethereum and Base), a transaction that appears in a block may be reorged out of the canonical chain. Servers accepting payments for high-value resources SHOULD wait for a chain-specific number of confirmation blocks before accepting a proof as final. For low-value micropayments on Base (an optimistic rollup with fast soft-finality), a single block confirmation is typically sufficient.¶

Verification services MUST check that the transaction receipt status indicates success (i.e., it was not reverted), not merely that a transaction with the given hash exists.¶

10.6. Nonce Store Exhaustion

An adversary could generate large numbers of initial requests to force the server to allocate nonces, potentially exhausting memory if the nonce store grows without bound. Server implementations MUST periodically prune expired nonces and SHOULD rate-limit the issuance of payment challenges per IP address or session.¶

10.7. Header Injection

The X-FADP-Required and X-FADP-Proof header values are JSON strings. Implementations MUST parse these with a conformant JSON parser and MUST NOT construct them via string interpolation without proper escaping, to prevent injection attacks.¶

10.8. Transport Security

All FADP exchanges, including calls to the verification service, MUST be made over TLS (HTTPS). Transmitting payment challenges or proofs over plaintext HTTP exposes the nonce to network adversaries, potentially enabling race-condition replay attacks.¶

10.9. Agent Spending Controls

FADP does not define agent-side spending controls; these are the responsibility of the agent runtime. However, agent implementors MUST validate the requested amount in the payment challenge against a pre-configured limit before executing any transfer. Failing to do so could allow a malicious server to drain an agent's wallet by issuing artificially large payment challenges.¶

11.1. HTTP Header Field Registration

This document requests registration of the following header fields in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" maintained at https://www.iana.org/assignments/http-fields/.¶

Header Field Name

X-FADP-Required¶

Status

provisional¶

Reference

This document, Section 4.1¶

Header Field Name

X-FADP-Proof¶

Status

provisional¶

Reference

This document, Section 4.2¶

11.2. Media Type

No new media types are registered by this document. All message bodies are application/json as defined in [RFC8259].¶

12.1. Reference Implementations

Reference implementations of the server middleware (fadpGate()) and client interceptor (fadpFetch()) are available as open-source software:¶

• fluid-fadp (npm): server middleware and standalone client interceptor for Node.js / TypeScript. Repository: https://github.com/fluidbase9/fadp¶
• fluid-wallet-agentkit (npm): full agent SDK incorporating FADP auto-pay via the agent.fetch() method. Repository: https://github.com/fluidbase9/fluidwalletbase¶
• fluid-fadp-proxy (npm): a ready-made reverse proxy that gates commercial AI service APIs (OpenRouter, RunPod, Vast.ai, Spheron) behind FADP payment walls. Repository: https://github.com/fluidbase9/fadp-proxy¶

12.2. Nonce Storage in Distributed Deployments

For single-process servers, an in-memory Map with periodic TTL pruning is sufficient. For multi-instance deployments, a shared store with atomic operations is required. A Redis SET NX EX command provides an atomic "set if not exists with expiry" primitive suitable for nonce issuance; a Redis DEL returning the count of deleted keys provides atomic consumption.¶

12.3. Amount Precision

Token amounts MUST be represented as decimal strings to avoid floating-point precision loss. On-chain, USDC uses 6 decimal places; the string "0.001" corresponds to on-chain value 1000 (in the smallest unit). Implementations MUST convert between decimal string and on-chain integer representation using fixed-point arithmetic, not IEEE 754 floating-point.¶

12.4. Cross-Origin Resource Sharing

Browser-based agent implementations require that X-FADP-Required be listed in the Access-Control-Expose-Headers response header for the 402 response. Servers MUST set this header when cross-origin clients are expected.¶