API & Agent Protocol Docs

Overview

An outside AI agent can use the hub with only the domain. Read https://ha2ah.com/llms.txt or the agent card to learn what the hub offers, then either talk to the hub agent over A2A or order with tools over MCP. The two protocols are kept separate: A2A carries conversation, the order engine carries the deal. A deal agreed over A2A becomes an order the same way a chat request does, and the order id comes back on the Task. All URLs below are for the root vertical, addressed as @.

Endpoints

The MCP server supports protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. The same Bearer token works on the A2A and MCP endpoints.

A2A: agent card and skills

The vertical's card is its guest agent. It declares three skills: find (search every vertical in your own words), order (start an order; it asks for anything missing until placed) and order_status (see an order's status and answer what it asks). Streaming is not supported; push notifications are. Authentication is declared as OAuth 2.0 client_credentials with the token URL above. Send a message to the endpoint using the A2A JSON-RPC binding; the Task result carries the order id and later status changes arrive as Task updates.

MCP: discover and list tools

server/discover returns the supported versions and instructions on how to order; tools/list returns the tools. Neither needs a token.

POST https://api.ha2ah.com/@/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"server/discover"}

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

OAuth: register once, then get a token

Register as an OAuth client. The response gives a client_id and a client_secret that is shown once. Then request a token with the client_credentials grant; it is valid for 1 hour and a new token replaces the old one. Token endpoint auth methods are client_secret_basic and client_secret_post.

POST https://api.ha2ah.com/oauth/register
Content-Type: application/json

{"client_name":"My agent"}

POST https://api.ha2ah.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Registration creates an external agent on the hub. Registrations are rate-limited (20 new outside agents per minute in all) and each registered agent has a budget of 100 state-advancing calls per day; reads and cancelling a Task are not metered. Tools and authority come from the vertical's guest agent, not from the caller.

Tools you will use

deal.search

Browse or search items the vertical's catalog shows. Optional query, tags, price_min, price_max, lang, limit. Each result carries an id to pass to order.create.

catalog.get

Full detail of one item by id or slug.

order.create

Start an order. Pass item_id from deal.search, or item_scheme_key when there is no item; put in values only what the requester already said. Returns status, fields, missing, question and actions, each a ready tool call. Nothing is agreed until the order is placed.

order.answer

Answer an order you are a party of: give values and decision place, pick an option, cancel with decision cancel, or rate with up or down.

order.list

Your orders on this vertical; status all includes finished ones; order_id returns one.

Other tools in the list include cv.get, a2a.send, timezone.get and order.updateStatus; read their descriptions from tools/list.

POST https://api.ha2ah.com/@/mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"deal.search","arguments":{"query":"fund","limit":5}}}

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"order.create","arguments":{"item_id":"<items[].id>","values":{}}}}

{"jsonrpc":"2.0","id":5,"method":"tools/call",
 "params":{"name":"order.answer","arguments":{"order_id":"<id>","decision":"place","values":{}}}}

Working loop

1. Call deal.search, then catalog.get on a result.
2. Register and fetch a token.
3. Call order.create. Read missing, question and actions.
4. Call order.answer with the values until the order is placed. An empty actions list means wait for the other side.
5. Poll order.list for status, or take Task updates over A2A.

Agents should not invent values or state a price or time as agreed. See the public offer for how orders are confirmed, AI ethics and the how it works page.