Back to convrgent.ai

API Documentation

36 endpoints. x402 pay-per-call in USDC. No API keys needed.

How x402 works
1
POST your request to any endpoint
2
Receive HTTP 402 with payment details (amount, wallet, network)
3
Pay via CDP facilitator — get a payment proof
4
Retry with PAYMENT-SIGNATURE header — get your data
Payment Details
Protocolx402 v2
CurrencyUSDC
NetworksBase (eip155:8453) + Solana mainnet
EVM Payee0xc273...9882
Solana Payee7jw5B...o6fS
Discovery/.well-known/x402

All Endpoints

KYH (26)    BLAH (3)    KYB (7)

KYH — Single-Human Endpoints

POST/api/kyh/natal-chart
KYH$0.50

Western astrology natal chart — planetary positions, houses, aspects, Sun/Moon/Rising signs, personality interpretation.

Input
birth_date (required)birth_time (optional, defaults noon)location (city string, auto-resolved)
POST/api/kyh/communication
KYH$0.05

Communication style profiler — tone, directness, formality, persuasion triggers, trust signals, writing style analysis.

Input
text_samples (array)observations (array)natal_data (optional)demographics (optional)
POST/api/kyh/psych
KYH$1.00

12 psychological dimensions — OCEAN (Big Five), attachment style, risk tolerance, cognitive style, locus of control, authority orientation.

Input
text_samples (array)observations (array)natal_data (optional)demographics (optional)
POST/api/kyh/socionics
KYH$1.00

16-type cognitive function typing (ILE, SEI, ESE, LII, etc.) with function stacks and intertype relations.

Input
text_samples (array)observations (array)responses (questionnaire)natal_data (optional)
POST/api/kyh/human-design
KYH$0.75

Bodygraph — type, strategy, authority, profile, defined/undefined centers, channels, gates, Incarnation Cross.

Input
birth_date (required)birth_time (required)location (required, city string)
POST/api/kyh/mbti
KYH$0.50

16 Personality Types with 4 dichotomies, cognitive function stacks, and confidence scores.

Input
text_samples (array)observations (array)natal_data (optional)
POST/api/kyh/numerology
KYH$0.25

Life Path, Expression, Soul Urge, Birthday Number, Personal Year/Month, karmic debts. Pythagorean + Chaldean.

Input
birth_date (required)legal_name (optional)common_name (optional)
POST/api/kyh/chinese-astrology
KYH$0.75

Chinese zodiac, Four Pillars of Destiny (BaZi), Day Master, Heavenly Stems, Earthly Branches, element balance.

Input
birth_date (required)birth_time (optional)location (optional)year_start (cny|lichun, optional)
POST/api/kyh/vedic
KYH$0.75

Vedic astrology (Jyotish) — sidereal chart, Nakshatras, Vimshottari Dasha, Yogas, planetary dignities.

Input
birth_date (required)birth_time (required)location (required)ayanamsa (lahiri|krishnamurti|raman, optional)
POST/api/kyh/enneagram
KYH$1.00

Enneagram type (1-9), wing, tritype, instinctual stack (sp/sx/so), integration/disintegration dynamics.

Input
text_samples (array)observations (array)responses (questionnaire)natal_data (optional)
POST/api/kyh/convergence
KYH$2.50

24 canonical traits synthesized from 2+ framework outputs — agreements, tensions, unique insights.

Input
outputs (object with 2+ framework results, required)include_narrative (optional)

KYH — Orchestration

POST/api/kyh/portrait
KYH$5.00

Full 11-framework synthesis into HUMAN.md — the complete portable personality portrait for any agent.

Input
birth_date, birth_time, locationtext_samples (array)observations (array)responses (optional)context (optional)
POST/api/kyh/agent-prompt
KYH$1.50

Concise system prompt for agent injection — tells an AI exactly how to communicate with this person.

Input
birth_date, birth_time, location (optional)text_samples (array)observations (array)context (optional)

KYH — Multi-Human

POST/api/kyh/multi/compatibility
KYH$5.00

Two-person match across 5+ dimensions — synastry, intertype relations, BaZi, Enneagram, Life Path.

Input
human_a (birthData, textSamples, observations)human_b (same)relationship_type (romantic|business|coworkers|etc)
POST/api/kyh/multi/bridge
KYH$2.00

Communication mediation guide — how person A should talk to person B in a specific scenario.

Input
human_a, human_b (profile data)scenario (delivering-feedback|resolving-conflict|etc)
POST/api/kyh/multi/conflict
KYH$2.00

Friction prediction — clash analysis, disagreement triggers, personality-based prevention strategies.

Input
human_a, human_b (profile data)relationship_type (optional)stress_level (low|moderate|high, optional)
POST/api/kyh/multi/team
KYH$6–$10

Group analysis for 2-10 people — roles, gaps, power dynamics, pairwise highlights, recommendations.

Input
members (array of 2-10, each with name + profile data)context (optional)
POST/api/kyh/multi/evolution
KYH$3.00

Relationship change over time — trend analysis, inflection points, trust trajectory.

Input
human_a, human_b (profile data)snapshots (2-20 timestamped observations)context (optional)

KYH — Vault (Profile Storage)

POST/api/kyh/vault/create
KYH$0.10

Create a new personality vault — store a human’s profile data for reuse across endpoints without re-profiling.

Input
human_id (required)profile_data (required — any framework outputs)metadata (optional — name, context, tags)
POST/api/kyh/vault/update
KYH$0.05

Update an existing vault — add new framework results or refresh stale data.

Input
vault_id (required)profile_data (partial update)metadata (optional)
POST/api/kyh/vault/read
KYH$0.02

Read a vault — retrieve stored profile data for use in other endpoints.

Input
vault_id (required)frameworks (optional — filter to specific frameworks)
POST/api/kyh/vault/list
KYH$0.02

List all vaults owned by this wallet — paginated, filterable.

Input
page (optional)limit (optional)tags (optional filter)
POST/api/kyh/vault/delete
KYH$0.01

Delete a vault — permanently removes stored profile data.

Input
vault_id (required)

KYH — State & Timing Intelligence

POST/api/kyh/state
KYH$0.75

Detect a human’s current psychological state — energy level, stress, openness to new ideas, decision readiness, emotional tone. Real-time context for when to push and when to hold back.

Input
text_samples (array — recent messages)observations (optional)vault_id (optional — uses stored profile for baseline comparison)
POST/api/kyh/timing
KYH$1.00

Timing intelligence — best time to reach out, optimal cadence, receptivity windows based on personality + current state. Tells your agent when to act, not just how.

Input
vault_id or profile_data (required)objective (required — pitch, follow-up, feedback, etc.)channel (optional — email, call, chat)timezone (optional)

KYH — Micro Queries

POST/api/kyh/micro
KYH$0.02–$0.07

Single data point queries — communication_style ($0.07), single_psych_dimension ($0.02), socionics_dimension ($0.05), trust_level ($0.02), autonomy_preference ($0.02), cultural_context ($0.02).

Input
query (type string)text_samples (array)observations (optional)Additional fields per query type
GET/api/kyh/health
KYHfree

Service health check.

BLAH — Be Like A Human

POST/api/blah/adapt
BLAH$0.75

Context-aware communication adaptation strategy — how an agent should talk to a specific human.

Input
context (domain, objective, relationship_stage, channel, urgency — required)kyh_profile (optional, enables Mode 1)agent_role (optional)
POST/api/blah/respond
BLAH$0.35

Real-time response coaching with emotion detection — ranked response options for a given message.

Input
human_message (required)objective (required)history (optional)kyh_profile (optional)tone (optional override)
POST/api/blah/deescalate
BLAH$1.00

Step-by-step de-escalation script using NVC framework — for tense situations.

Input
situation (required)escalation_level (1-5, required)domain (required)agent_fault (optional)kyh_profile (optional)prior_attempts (optional)

KYB — Know Your Buyer (Coming Soon)

POST/api/kyb/profile
KYB$1.50

Buyer motivation, decision style, impulse/loyalty scores, Cialdini persuasion susceptibility map.

Input
kyh_profile or buyer_description (text)
Coming soon
POST/api/kyb/pitch
KYB$2.00

Personality-matched sales pitch with framing, opening hook, objection preemption, CTA.

Input
product (required)channel (optional)kyh_profile or buyer_description
Coming soon
POST/api/kyb/objections
KYB$1.25

Predicted objections ranked by probability with personality-matched rebuttals.

Input
product context (optional)price_point (optional)kyh_profile or buyer_description
Coming soon
POST/api/kyb/pricing
KYB$1.00

Price psychology — anchoring, framing, discount sensitivity, urgency triggers, payment preferences.

Input
product_price (required)product_description (optional)kyh_profile or buyer_description
Coming soon
POST/api/kyb/content
KYB$1.50

Content strategy for conversion — types, formats, channels, cadence, social proof preference.

Input
industry (optional)product_category (optional)kyh_profile or buyer_description
Coming soon
POST/api/kyb/cultural
KYB$1.00

Hofstede cultural adaptation for 14 markets — messaging norms, negotiation style, taboos.

Input
target_market (required)product (optional)kyh_profile or buyer_description
Coming soon
POST/api/kyb/committee
KYB$4.00

Multi-stakeholder B2B messaging matrix (2-10 stakeholders) — role-specific messaging.

Input
product_description (required)stakeholders (array of 2-10 with role + personality data)
Coming soon

Make Any Agent Personality-Aware

Your agent treats every human the same. These 15 lines of code fix that.

Click any use case to see the problem, the fix, and working code.

Sales Agent

Close deals by understanding the buyer

Your sales agent sends the same pitch to every prospect. An analytical buyer gets the same enthusiasm dump as a visionary one. Conversion suffers because the message doesn't match the mind.

+

Support Agent

De-escalate by reading the human

Your support bot responds to angry customers with scripted empathy. It doesn't know if this person needs facts to calm down or emotional validation first. Generic de-escalation makes some people angrier.

+

Hiring Agent

Hire for the team, not just the role

Your hiring agent screens for skills and experience. It has no idea whether this candidate will clash with the team lead's management style or fill the cognitive gap the team actually needs.

+

Coaching Agent

Coach the person, not the problem

Your coaching bot gives the same advice to everyone. "Set SMART goals. Practice active listening. Try the Pomodoro technique." It doesn't know that this person's real blocker is their conflict avoidance, not their time management.

+

Content Agent

Write for the audience, not at them

Your content agent produces one version of everything. The same blog post, the same email, the same landing page copy — regardless of whether the reader is an analytical skeptic or an enthusiastic early adopter.

+

Negotiation Agent

Win the deal without losing the relationship

Your negotiation agent uses the same tactics for everyone. Anchoring high works on some people and backfires spectacularly on others. A risk-averse buyer needs safety signals. A dominance-oriented buyer needs to feel like they won.

+

Product Feedback Agent

Hear what users mean, not just what they say

Your feedback agent treats a 3-star review from an analytical introvert the same as a 3-star review from an expressive extrovert. But they mean completely different things. The introvert rating 3 stars is probably satisfied. The extrovert rating 3 stars is probably disappointed. Without personality context, your product roadmap is built on misinterpreted signals.

+

Onboarding Agent

Onboard the person, not just the user

Your onboarding flow is one-size-fits-all. Step 1, step 2, step 3, welcome email. But some users want to explore freely. Others want a structured guided tour. Some will watch every tutorial video. Others will skip straight to the API docs. The drop-off isn't a funnel problem — it's a personality mismatch problem.

+

Integration

Four ways to connect. Use whichever fits your stack.

MCP Server

Native integration for Claude Desktop, GPT, and other MCP-compatible clients. 29 tools mapping 1:1 to API endpoints.

Run: npx tsx src/mcp/index.ts
Transport: stdio (standard MCP protocol)
29 tools (26 KYH + 3 BLAH)
Calls production API over HTTP

A2A Protocol

Agent-to-agent communication via JSON-RPC. 29 skills with structured task management.

Agent Card: GET /.well-known/agent.json
JSON-RPC: POST /api/a2a
Supports: message/send, message/stream (SSE), tasks/get
Protocol v0.3.0

ERC-8004 Identity

On-chain agent identity registered on Base and Solana for trust and discovery.

Base: Agent ID 27418
Solana: ARaehWV...kc7U
Contract: 0x8004A169...a432
IPFS card with 29 tools + dual wallets

x402 Discovery

Machine-readable endpoint catalog for automated agent discovery.

GET /.well-known/x402
OpenAPI: GET /api/openapi.json
Listed on x402 Bazaar + AgentCash
x402scan Composer agents available