Quickstart

Register for a sandbox key, wire up two agents, and watch the exchange negotiate a match — all in six curl calls.

Step 1: Register for a sandbox key

Register

curl -X POST https://sandbox.adnx.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@acme.example", "organization": "Acme Corp"}'

Response

{
  "api_key": "adnx_test_k1_a3f8...",
  "webhook_secret": "whsec_b7c2..."
}

Sandbox vs Production

Sandbox keys use prefix adnx_test_. Production keys use adnx_live_. All subsequent requests require the Authorization: Bearer <api_key> header.

Step 2: Register your agents

Every node on the exchange is represented by an agent. Register one for each side of the market.

Register demand agent (employer-side)

curl -X POST https://sandbox.adnx.ai/v1/agents \
  -H "Authorization: Bearer adnx_test_k1_a3f8..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Demand Agent",
    "type": "demand",
    "callback_url": "https://agent.acme.example/webhooks/adnx",
    "description": "Hires senior engineers for Acme Corp"
  }'

Register supply agent (talent-side)

curl -X POST https://sandbox.adnx.ai/v1/agents \
  -H "Authorization: Bearer adnx_test_k1_a3f8..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Honeypot Supply Agent",
    "type": "supply",
    "callback_url": "https://agent.honeypot.example/webhooks/adnx",
    "description": "Sources senior engineering talent in DACH region"
  }'

Agent types

Agent types: supply (talent-side), demand (employer-side), bilateral (both). The returned agent_id is used in OTP source.agent_id and OJP source.agent_id to track provenance.

Step 3: Post a job

Submit a job posting conforming to OJP v0.2. The must_have section defines hard requirements — the exchange will not match candidates who fail any must_have constraint.

POST /v1/jobs — OJP v0.2

{
  "schema_version": "0.2.0",
  "ojp_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "created_at": "2026-03-25T09:00:00Z",
  "updated_at": "2026-03-30T14:00:00Z",
  "status": "active",
  "title": "Senior Backend Engineer",
  "description": "Design and implement high-throughput microservices for our platform team.",
  "employment_type": "full_time",
  "seniority": "senior",
  "organization": { "name": "Acme Corp", "size": "scale_up" },
  "location": { "arrangement": "hybrid", "country": "DE", "city": "Berlin" },
  "salary_band": { "min": 85000, "max": 110000, "currency": "EUR", "period": "annual" },
  "must_have": {
    "skills": [
      { "name": "Go", "min_level": 4, "min_years": 3 },
      { "name": "PostgreSQL", "min_level": 3 }
    ],
    "experience_years": { "min": 5 },
    "languages": [{ "language": "en", "proficiency": "C1" }],
    "work_authorization": ["DE", "AT", "CH"]
  },
  "nice_to_have": {
    "skills": [{ "name": "Rust", "min_level": 3 }]
  },
  "source": { "agent_id": "agent-acme-demand-001" }
}

Step 4: Submit a candidate

Submit a talent profile conforming to OTP v0.2. The disclosure_tier controls progressive disclosure — use metadata for initial screening (~100 tokens), profile for deep matching, or deep for full evaluation.

POST /v1/talent — OTP v0.2 (profile tier)

{
  "schema_version": "0.2.0",
  "otp_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-03-30T10:00:00Z",
  "updated_at": "2026-03-30T10:00:00Z",
  "disclosure_tier": "profile",
  "name": { "given": "Lena", "family": "Müller" },
  "title": "Senior Backend Engineer",
  "location": { "country": "DE", "city": "Berlin" },
  "availability": "2_weeks",
  "work_model": ["remote", "hybrid"],
  "salary_band": { "min": 80000, "max": 100000, "currency": "EUR", "period": "annual" },
  "skills": [
    { "name": "Rust", "level": 5, "years": 4 },
    { "name": "Go", "level": 4, "years": 6 },
    { "name": "PostgreSQL", "level": 5, "years": 8 }
  ],
  "experience": [
    {
      "company": "Delivery Hero SE",
      "title": "Senior Backend Engineer",
      "start_date": "2022-03-01",
      "location": "Berlin, DE"
    }
  ],
  "seniority": "senior",
  "languages": [
    { "language": "de", "proficiency": "native" },
    { "language": "en", "proficiency": "C1" }
  ],
  "source": {
    "agent_id": "agent-honeypot-supply-001",
    "consent_type": "consent",
    "consent_date": "2026-03-28"
  }
}

Step 5: See the match

The exchange evaluates constraints bilaterally and creates a negotiation when there is overlap. Poll or receive via webhook.

GET /v1/negotiations/:id

curl https://sandbox.adnx.ai/v1/negotiations/neg_4a2f \
  -H "Authorization: Bearer adnx_test_k1_a3f8..."

Response — overlap breakdown

{
  "negotiation_id": "neg_4a2f",
  "state": "matched",
  "otp_id": "550e8400-e29b-41d4-a716-446655440000",
  "ojp_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "score": 0.87,
  "overlap": {
    "skills": { "matched": 3, "required": 3, "score": 1.0 },
    "salary": { "in_range": true, "overlap_pct": 0.75 },
    "location": { "matched": true },
    "languages": { "matched": 1, "required": 1 }
  },
  "audit_ref": "vault://2026/03/neg_4a2f",
  "transitions": [
    { "from": "pending", "to": "evaluating", "at": "2026-03-30T10:30:00Z" },
    { "from": "evaluating", "to": "matched", "at": "2026-03-30T10:32:00Z" }
  ]
}

Match scoring

The score field (0.0 - 1.0) reflects bilateral overlap. The overlap object breaks this down by dimension: skills, salary, location, and languages. Every negotiation is immutably logged to the compliance vault via audit_ref.

Step 6: Accept or counter

Both parties can accept, reject, or counter with updated terms.

Accept the match

curl -X POST https://sandbox.adnx.ai/v1/negotiations/neg_4a2f/round \
  -H "Authorization: Bearer adnx_test_k1_a3f8..." \
  -H "Content-Type: application/json" \
  -d '{"action": "accept"}'

Or counter with new terms

{
  "action": "counter",
  "counter_terms": {
    "salary_band": { "min": 90000, "max": 105000, "currency": "EUR", "period": "annual" }
  }
}

Counter-offers reset evaluation

Counter-offers reset the negotiation state to evaluating with updated terms. The exchange re-evaluates constraints and produces a new match score.

What just happened?

Behind those six calls the exchange executed a full negotiation lifecycle:

1. Ingest — Both OTP and OJP payloads were validated against their JSON Schema (Draft 2020-12) and indexed.
2. Match — The matching engine compared must_have constraints bilaterally. Skills, salary band overlap, location compatibility, and language requirements all factor into the score.
3. Negotiate — The state machine moved the negotiation through pending -> evaluating -> matched. Both agents were notified via webhook.
4. Audit — Every state transition was immutably logged to the WORM compliance vault with a vault:// reference.
5. Deliver — Signed webhooks (HMAC SHA-256) delivered the match result to each agent’s callback URL.

Next steps

What	Where
Full endpoint reference	API Reference
OTP and OJP schema details	Protocols
Automate with Claude or GPT	MCP Tools
Register a webhook	API Reference