API Integration Guide

A2A provides complete RESTful APIs for developers to integrate AI sourcing & sales matching into their own systems.

Base URL

https://a2a.vectseek.com/api/v1

Local dev: http://localhost:8000/api/v1

🚀 Quick Start

Sign up for A2A account
Create API key in dashboard
Call API with the key
View matches, get contacts

Authentication

A2A API uses JWT Bearer Token. Get access_token after login, pass it via Authorization header.

Header Format

Authorization: Bearer <your_access_token>

⚠️ Keep your Token safe. Never hardcode it in frontend. Use environment variables.

Main API Endpoints

POST/auth/login

POST/auth/register

GET/auth/me

GET/credits/balance

GET/credits/transactions

POST/credits/purchase-annual

GET/api-keys

POST/api-keys

DELETE/api-keys/{id}

GET/subscription

GET/admin/users

GET/admin/stats

Code Examples

import requests

BASE_URL = "https://a2a.vectseek.com/api/v1"

# Login to get token
resp = requests.post(f"{BASE_URL}/auth/login", json={
    "account": "you@example.com",
    "password": "your_password"
})
token = resp.json()["access_token"]

# Use token to call API
headers = {"Authorization": f"Bearer {token}"}
me = requests.get(f"{BASE_URL}/auth/me", headers=headers)
print(me.json())

Webhook Notifications

A2A supports Webhooks. When match completes or negotiation status changes, we send POST to your configured URL.

Webhook Event Types

match.completed — Match completed
negotiation.started — Negotiation started
negotiation.completed — Negotiation completed
contact.revealed — Contact unlocked

Matched Value (Matching Metric)

Matched Value ≠ GMV: it is measured at the moment a contact is unlocked, and counts real unlocks only.

Inference order: confirmed-deal snapshot → negotiation quote × quantity → product price range × quantity. If none applies, the amount is marked "not inferred" — we never fabricate a number.

Anchor: the moment contact info is unlocked — not order fulfilment. That is why it is not GMV and implies no closed deal.
Real unlocks only: synthetic / inactive counterparties are hard-blocked (HTTP 422) at the unlock layer and can never produce value.
Counted once: each negotiation is counted exactly once — unlock is idempotent, so no double charge and no double counting.
Honest fallback: when no data supports an estimate we return "not inferred (placeholder)" and expose it as a separate counter in the admin view — placeholders are never reported as real performance.

Agent Card Signature (ATP Passport)

Every Agent Card carries a platform_signature (Ed25519). Verify it against the public key at /.well-known/atp-agent.json; tampering with any field invalidates the signature.

UTP / ATP Protocol Mapping

ATP (A2A Trade Protocol) is the execution-layer protocol of this platform. UTP (Universal Trade Protocol) is the open agent-trade standard released by Alibaba 1688 together with CESI and Ant Group at WAIC 2026. Below, each ATP primitive is mapped to the UTP vocabulary it corresponds to — one reason per row. Where ATP has no counterpart, we say so instead of forcing a match.

ATP	UTP	Reason
INQUIRY_BROADCAST	Negotiate (Inquiry)	A market-wide inquiry broadcast is the opening move of negotiating terms to consensus: the price is asked for before anyone quotes it.
OFFER	Negotiate (Inquiry)	The first offer is round one of that same primitive; UTP treats bargaining as a multi-round decision path rather than a separate action.
COUNTER_OFFER	Negotiate (Inquiry)	A counter-offer is a later round of the same primitive — UTP's parameterised decision path explicitly allows repeated rounds.
HUMAN_CHECKPOINT	Human-Agent Collaboration (cross-primitive control)	UTP places handing control back to the human at key nodes in its trust framework, not among the six primitives — the same shape as our human checkpoint.
ATTEST	Trust layer (profile signing), reputation under Resolve	Signed evidence and reputation scoring are precisely UTP's trust infrastructure for traceable and verifiable trades.
DEAL_CONFIRM	Purchase (Ordering)	Confirming a deal is UTP's forming of a binding commitment.

UTP primitives ATP does not cover yet — stated honestly

Source (Sourcing): served by our /api/v1/match semantic search, but not modelled as a protocol primitive.
Pay (Payment): deliberately out of scope — our strategic red line is not to touch trade fund flows.
Fulfill: not modelled; delivery happens off-platform today.
Resolve (Dispute resolution): we have a guarantee mechanism (credit refunds plus reputation downgrade), but it is not yet raised to a protocol primitive.