A Best Current Practice for Agentic Interactions over HTTP

Autonomous software agents increasingly rely on HTTP to interact with external tools and services. However, the lack of a standardized interaction pattern has resulted in a fragmented landscape where each service requires a bespoke integration, often demanding fealty to a complex SDK or proprietary middleware. This trend risks creating a new "tyranny of the SDK," carving the nascent machine economy into walled gardens that stifle innovation and interoperability. This document outlines a Best Current Practice (BCP) for designing agent-facing services that rejects this contrived complexity and returns to first principles. It leverages the fundamental simplicity and robustness of HTTP as the primal protocol for agentic interaction. The goal is to reduce complexity, eliminate the need for heavyweight SDKs, and foster an open, federated ecosystem where the agent is treated as the primary user. These recommendations codify the successful patterns of the Agentic Hypercall Protocol (AHP), which serves as the reference implementation for this BCP. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119.

The core principle of this BCP is the Agentic Hypercall: a simple, RESTful pattern for tool invocation.

All actions are GET requests. Tools are paths. Parameters are query strings.

To ensure safety, predictability, and cacheability, services intended for agentic consumption MUST expose all idempotent, read-only, or state-retrieving actions as HTTP GET methods. The specific tool to be invoked MUST be identified by the URI path. All parameters required for the action MUST be passed as URL query string parameters.

To facilitate automated discovery of available tools, agent-facing servers MUST provide a machine-readable definition of their services. It is RECOMMENDED that an OpenAPI 3.0+ specification be made available at a stable, well-known URI path, such as `/openapi` or `/.well-known/openapi.json`.

To secure protected resources, this BCP recommends a two-step, stateless authentication scheme.

An agent MUST first obtain a temporary bearer token by making a GET request to a dedicated authentication endpoint (e.g., `/auth`). This request MUST include a pre-shared key, provided by the human user, as a query parameter (e.g., `?token=USER_PROVIDED_KEY`). The server MUST validate this key. Upon success, it MUST return a JSON object containing the temporary `bearer_token`.

For all subsequent calls to protected tool endpoints, the agent MUST include the `bearer_token` as a query parameter. The bearer token SHOULD be a stateless, signed token (e.g., a simplified JWT) containing claims such as an agent identifier and an expiration timestamp. This allows any server in a federated system to verify the token without needing access to a central token store.

A tool has intrinsic value. To foster a healthy and honest market for digital services, this BCP proposes the "Aperture Principle": a tool can declare its own cost, and the network must honor it. This is achieved by formalizing the use of the `402 (Payment Required)` status code.

When an agent requests a resource that requires payment, the server SHOULD return a 402 status code. The response body **MUST** be a JSON object containing details of the required payment. The JSON object SHOULD contain the following keys:

`cost`: A string representing the decimal amount required for the service.
`currency`: A string identifying the ledger or currency type (e.g., "USD", "EUR", "BTC-LN").
`destination`: A string containing the payment address or invoice. For Bitcoin's Lightning Network, this would be the BOLT 11 invoice.
`description`: A human-readable string explaining the charge (OPTIONAL).

Example 402 Response for Bitcoin Lightning Network: HTTP/1.1 402 Payment Required Content-Type: application/json { "cost": "100", "currency": "BTC-LN", "destination": "lnbc10u1p3z2y7xpp5j3c2y...", "description": "API call to /longer_qr_code" }

Upon receiving a 402 response, an agent can parse the body to decide if the cost is acceptable and if it possesses the means to pay. If it proceeds, it can then retry the original HTTP GET request, including proof of payment as specified by the service (e.g., in a new `Authorization` header or as a query parameter like `invoice_id`).

Standardizing these simple patterns provides immense benefits. It lowers the barrier to entry for new tool creators, allows agents to seamlessly switch between service providers, and creates a transparent, native economic layer for the machine economy. By formalizing the use of the 402 code, we avoid the need for complex, out-of-band billing APIs and instead embed commerce directly into the protocol where it belongs, fostering a federated world of sovereign, interoperable nodes.

This BCP recommends a specific structure for the payload of an HTTP 402 response. Future work may propose the creation of a registry for common "currency" identifiers to promote interoperability between different payment systems.

Service providers must protect against denial-of-service attacks and validate all inputs from agents. Agents must protect their payment credentials and verify the identity of the services they interact with, typically via TLS. The stateless bearer token scheme is the RECOMMENDED method for securing protected resources.