NIP-5 defines a Fiat Proxy Service that enables AI Agents (identified by DIDs as per NIP-1) to interact with fiat payment systems. This service acts as a bridge, allowing agents to perform actions like initiating payments or verifying payment status through a standardized API. Fiat Proxy services are discoverable via their DID documents, and all API interactions are authenticated using NIP-2.
AI Agents often need to interact with traditional financial systems, which typically require authenticated API access, KYC/AML compliance, and handling of sensitive payment information. Directly embedding these capabilities into every agent is impractical and insecure. A Fiat Proxy Service provides a secure and standardized way for agents to access these systems.
| Pain point | Effect | Solution offered by NIP-5 |
|---|---|---|
| Agents need to trigger fiat payments | Complex integration with diverse payment gateways | Standardized API via Fiat Proxy |
| Agents need to verify payment status | Requires polling or webhooks | Standardized API for status checks |
| Security and Compliance | Agents handling raw payment credentials is risky | Proxy handles credentials and compliance; Agent interacts via DID authentication |
| Service Discovery | How do agents find a suitable Fiat Proxy? | Proxies declare their services in their DID documents (NIP-1) |
Fiat Proxy services declare their offerings as part of their DID document (NIP-1) using the service property. This allows AI Agents and their clients to discover and interact with Fiat Proxy services in a decentralized manner.
Each Fiat Proxy service endpoint in the DID document’s service array MUST include:
id: A URI that conforms to the DID Core specification, typically a fragment identifier relative to the Proxy’s DID (e.g., did:example:fiatproxy123#fiat-proxy-service).type: A string identifying the type of service. For NIP-5 Fiat Proxy services, this MUST be FiatProxyServiceNIP5.serviceEndpoint: A URI specifying the HTTPS base URL for the Fiat Proxy’s API.metadata: An optional JSON object containing additional information about the service, such as:
name: (String) A human-readable name for the Fiat Proxy service.supported_currencies: (array of String) A list of ISO 4217 currency codes supported (e.g., ["USD", "EUR"]).supported_payment_methods: (array of String) A list of payment methods supported (e.g., ["credit_card", "paypal"]).regions_served: (array of String) A list of ISO 3166-1 alpha-2 country codes where the service is available.fee_structure_url: (String) A URL pointing to documentation about the proxy’s fee structure.Example DID Document Snippet for a Fiat Proxy:
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:fiatproxy456",
// ... other DID document properties like verificationMethod, authentication, etc. ...
"service": [
{
"id": "did:example:fiatproxy456#fiat-proxy",
"type": "FiatProxyServiceNIP5",
"serviceEndpoint": "https://proxy.example.com/api/v1",
"metadata": {
"name": "Example Global Fiat Proxy",
"supported_currencies": ["USD", "EUR", "JPY"],
"supported_payment_methods": ["credit_card", "bank_transfer"],
"regions_served": ["US", "CA", "GB"],
"fee_structure_url": "https://proxy.example.com/fees"
}
}
// ... other services offered by the DID subject ...
]
}
Clients discover Fiat Proxy services by resolving their DIDs and looking for service entries with type: "FiatProxyServiceNIP5". The serviceEndpoint URI is then used to interact with the Proxy’s API.
All API requests to the Fiat Proxy serviceEndpoint MUST be authenticated according to the NIP-2: DID-Based Authentication Protocol. Specifically, clients (AI Agents) MUST use the HTTP-based authentication mechanism defined in NIP-2, which involves sending an Authorization header with the DIDAuthV1 <credentials> scheme. The <credentials> are a Base64url encoded JSON string containing the signer_did, key_id, and signature_value over the relevant parts of the request, as detailed in NIP-2.
The contentToSign for NIP-2 authentication in the context of NIP-5 API calls MUST include the full HTTP request body and a timestamp and nonce as specified in NIP-2 to prevent replay attacks. The domainSeparator for NIP-5 should be a clearly defined string like "NUWA_FIAT_PROXY_NIP5_V1:".
(Note: The following API endpoints are illustrative. Specific implementations may vary but should cover these core functionalities. Fiat Proxy providers should publish detailed API documentation. All endpoints require NIP-2 authentication.)
POST /payments/initiate
{
"agent_did": "did:example:agent:xyz", // This is implicitly verified by NIP-2's signer_did
"recipient_details": {
"type": "bank_account", // or "paypal_email", "crypto_address_for_stablecoin", etc.
"account_number": "...",
"routing_number": "...",
"beneficiary_name": "..."
},
"amount": "100.00",
"currency": "USD",
"memo": "Payment for services rendered by Agent XYZ",
"timestamp": 1678886400, // Unix timestamp, part of contentToSign for NIP-2
"nonce": "a1b2c3d4e5f67890" // Unique random string, part of contentToSign for NIP-2
}
{
"payment_id": "txn_123abc",
"status": "pending", // or "processing", "requires_action"
"details": "Payment initiated successfully."
}
GET /payments/{payment_id}/status
payment_id: The ID of the payment returned by the initiate endpoint.contentToSign for NIP-2 would include relevant request parameters like payment_id, a timestamp, and a nonce. These might be passed as query parameters or in the body if applicable, or constructed as per NIP-2 guidelines for GET requests.{
"payment_id": "txn_123abc",
"status": "completed", // or "pending", "failed", "refunded"
"timestamp": "2025-05-15T10:30:00Z",
"transaction_details": { /* ... specific details from payment processor ... */ }
}
sequenceDiagram
participant Agent as AI Agent (DID)
participant ClientApp as Client Application/User
participant ProxyDID as Fiat Proxy (DID Resolution)
participant ProxyAPI as Fiat Proxy API
participant PaymentGateway as External Payment Gateway
ClientApp->>Agent: Request to make a payment
Agent->>Agent: Identify need for Fiat Proxy
Agent->>ProxyDID: Resolve Fiat Proxy DID (e.g., did:example:fiatproxy456)
ProxyDID-->>Agent: Fiat Proxy DID Document
Agent->>Agent: Parse service endpoint for "FiatProxyServiceNIP5"
Agent->>ProxyAPI: POST /payments/initiate (Authenticated per NIP-2)
ProxyAPI->>ProxyAPI: Verify Agent's signature (as per NIP-2)
ProxyAPI->>ProxyAPI: Perform KYC/AML checks if necessary
ProxyAPI->>PaymentGateway: Initiate payment via PSP APIs
PaymentGateway-->>ProxyAPI: Payment status (e.g., pending)
ProxyAPI-->>Agent: { payment_id, status: "pending" }
ClientApp->>Agent: (Later) Check payment status
Agent->>ProxyAPI: GET /payments/{payment_id}/status (Authenticated per NIP-2)
ProxyAPI->>PaymentGateway: Query payment status
PaymentGateway-->>ProxyAPI: Payment status (e.g., completed)
ProxyAPI-->>Agent: { payment_id, status: "completed", details }
Agent-->>ClientApp: Payment completed
DID-based Service Discovery: Using DID documents for service discovery aligns NIP-5 with NIP-1 and NIP-3, promoting a consistent, decentralized approach. Fiat Proxy providers can advertise their capabilities (supported currencies, regions, etc.) directly within their DIDs, allowing agents or their users to select appropriate proxies.
Agent-Centric Authentication (via NIP-2): By mandating NIP-2 for authentication, NIP-5 ensures that actions are authorized by the AI Agent’s DID in a standardized and secure manner. This leverages the general-purpose DID authentication mechanism, enhancing security and accountability.
Abstraction of Complexity: The Fiat Proxy handles the complexities of interacting with various payment gateways, managing credentials, and dealing with compliance requirements. This simplifies the development of AI Agents that need fiat payment capabilities.
This NIP defines a new service type and discovery mechanism. Systems not aware of FiatProxyServiceNIP5 in DID documents will not be able to discover or interact with these services. Authentication relies on NIP-2; clients and services must implement NIP-2.
FiatProxyServiceNIP5 entry in the service array.serviceEndpoint and metadata (e.g., supported_currencies).payment_id with pending status.payment_id.completed, failed).Copyright and related rights waived via CC0.