Quickstart

Deal to settlement in a handful of calls, against the live demo environment. Every command below was run verbatim against the demo API; the outputs shown are what it returned. You need curl and jq. No API key required.

0. Point at the demo and reset it

BASE=https://sales-kernel-demo.vercel.app

# Reset the shared demo state (re-seeds the two demo closers, Dana Reyes and Marcus Webb)
curl -s -X POST $BASE/demo/reset

{"reset":true,"seeded":["Dana Reyes","Marcus Webb"]}

1. Sell — create a deal and run it until it escalates

POST /forsale/sell creates a Deal and advances it stage by stage. The agent works sourced → qualified → meeting; then the Mandate’s humanIf.minDealSizeUsd: 25000 rule escalates the closer Role on this $80,000 deal — a fully-briefed, commission-priced Gig is posted and the response tells you so.

curl -s -X POST $BASE/forsale/sell \
  -H 'content-type: application/json' \
  -d '{
    "account": { "name": "Acme Robotics", "industry": "Enterprise SaaS", "actor": "B2B" },
    "listValueUsd": 80000,
    "mandate": {
      "staffing": { "closer": { "humanIf": { "minDealSizeUsd": 25000 } } },
      "commissionPct": 0.1
    }
  }' > escalation.json

GIG=$(jq -r '.gig.id' escalation.json)
DEAL=$(jq -r '.gig.dealId' escalation.json)
CLOSER=$(jq -r '.suggestedClosers[0].closer.id' escalation.json)

{
  "escalated": true,
  "role": "closer",
  "gig": {
    "id": "gig_0003",
    "status": "open",
    "dealId": "deal_0001",
    "role": "closer",
    "brief": {
      "account": { "name": "Acme Robotics", "industry": "Enterprise SaaS", "actor": "B2B" },
      "listValueUsd": 80000,
      "stage": "meeting",
      "signals": [],
      "floorUsd": 64000,
      "activity": [
        { "by": "service", "stage": "sourced",   "note": "deal created" },
        { "by": "agent",   "stage": "qualified", "note": "BANT qualified: budget confirmed, champion identified" },
        { "by": "agent",   "stage": "meeting",   "note": "discovery call booked and held" }
      ]
    },
    "pricing": { "kind": "commission", "pct": 0.1 }
  },
  "suggestedClosers": [
    { "closer": { "id": "closer_0001", "name": "Dana Reyes", "industries": ["Enterprise SaaS", "Insurance"], … }, "score": 2.5, … },
    { "closer": { "id": "closer_0002", "name": "Marcus Webb", "industries": ["Coaching", "Real Estate"], … }, "score": 0.5, … }
  ]
}

Note the Brief: the closer inherits the full account context, stage history, Signals, and the negotiation floor (floorUsd: 64000 — 80% of list, the platform default floorPct). The price tag (10% commission) is fixed at post time and visible before claiming.

2. Claim the gig

The response ranked the pool; Dana Reyes scores highest on industry fit. Claim on her behalf:

curl -s -X POST $BASE/closers/gigs/$GIG/claim \
  -H 'content-type: application/json' \
  -d "{\"closerId\":\"$CLOSER\"}"

3. Work the deal — humans propose through the same gate

Every advance under a claimed Gig — intermediate stages included — is a Proposal to the deal’s gate on api.forsale, which commits or refuses it:

curl -s -X POST $BASE/closers/gigs/$GIG/advance \
  -H 'content-type: application/json' \
  -d '{"advanceTo":"proposal","note":"proposal sent after demo"}' | jq '.deal.stage'
# "proposal"

curl -s -X POST $BASE/closers/gigs/$GIG/advance \
  -H 'content-type: application/json' \
  -d '{"advanceTo":"negotiation","note":"redlines in"}' | jq '.deal.stage'
# "negotiation"

4. Watch the gate refuse a below-floor close

curl -s -w '\nHTTP %{http_code}\n' -X POST $BASE/closers/gigs/$GIG/advance \
  -H 'content-type: application/json' \
  -d '{"advanceTo":"closed_won","valueUsd":50000,"note":"buyer pushed hard"}'

{"error":"deal gate refused the proposal","gate":{"error":"proposed close $50000 is below the floor $64000 (80% of list)"}}
HTTP 422

HTTP 422 — the gate refused, even though a human proposed it. The Deal stays at negotiation and the Gig stays claimed; nothing to undo.

5. Close within the floor

curl -s -X POST $BASE/closers/gigs/$GIG/advance \
  -H 'content-type: application/json' \
  -d '{"advanceTo":"closed_won","valueUsd":74000,"note":"multi-year term won it back"}' \
  | jq '{deal: .deal.stage, gig: .gig.status, payouts: .closer.payouts}'

{
  "deal": "closed_won",
  "gig": "fulfilled",
  "payouts": [
    { "gigId": "gig_0003", "dealId": "deal_0001", "kind": "commission", "amountUsd": 7400 }
  ]
}

The gate commits closed_won at $74,000. The Gig fulfills, and the commission — 10% as declared in the Mandate — lands on Dana’s payout ledger and her Register records the win.

6. Settlement — billed on outcome, nothing on effort

curl -s $BASE/forsale/deals/$DEAL/settlement | jq .

{
  "finalValueUsd": 74000,
  "closerCommissionUsd": 7400,
  "platformFeeUsd": 3700,
  "feesSettledUsd": 0,
  "netToSellerUsd": 62900
}

The Settlement exists only because the Deal closed won: 5% platform fee, the closer commission as declared, fees already settled shown as a line item. A deal that closes lost settles nothing.

Next: Concepts — the six terms the API is built on.