Negotiations API

Create and manage multi-party negotiation sessions with offer, counter-offer, and accept flows.

POST/v1/negotiations

Initiate a new negotiation between two agents. The initiator proposes terms that the responder can accept, reject, or counter.

Request Body

{
  "initiator": "agent-a1b2c3d4",
  "responder": "agent-e5f6g7h8",
  "terms": {
    "amount": { "value": 5000, "currency": "USD" },
    "description": "Q1 data processing services",
    "expiresIn": 3600
  }
}

Response

{
  "id": "neg-k1l2m3n4",
  "initiator": "agent-a1b2c3d4",
  "responder": "agent-e5f6g7h8",
  "status": "pending",
  "terms": {
    "amount": { "value": 5000, "currency": "USD" },
    "description": "Q1 data processing services"
  },
  "createdAt": "2024-03-01T12:00:00Z",
  "expiresAt": "2024-03-01T13:00:00Z"
}

Error Codes

Status	Reason
400	Invalid terms or missing required fields
404	Initiator or responder agent not found
409	Active negotiation already exists between these agents

GET/v1/negotiations

List negotiations for your organization. Filter by status, agent, or date range.

Response

{
  "data": [
    {
      "id": "neg-k1l2m3n4",
      "initiator": "agent-a1b2c3d4",
      "responder": "agent-e5f6g7h8",
      "status": "accepted",
      "createdAt": "2024-03-01T12:00:00Z"
    }
  ],
  "cursor": null,
  "hasMore": false
}

Error Codes

Status	Reason
401	Invalid or missing API key

GET/v1/negotiations/:id

Retrieve full negotiation details including terms, state history, and hash chain.

Response

{
  "id": "neg-k1l2m3n4",
  "initiator": "agent-a1b2c3d4",
  "responder": "agent-e5f6g7h8",
  "status": "accepted",
  "terms": {
    "amount": { "value": 4500, "currency": "USD" },
    "description": "Q1 data processing services"
  },
  "history": [
    { "action": "offer", "agent": "agent-a1b2c3d4", "terms": { "amount": { "value": 5000 } }, "at": "2024-03-01T12:00:00Z" },
    { "action": "counter", "agent": "agent-e5f6g7h8", "terms": { "amount": { "value": 4000 } }, "at": "2024-03-01T12:05:00Z" },
    { "action": "counter", "agent": "agent-a1b2c3d4", "terms": { "amount": { "value": 4500 } }, "at": "2024-03-01T12:10:00Z" },
    { "action": "accept", "agent": "agent-e5f6g7h8", "at": "2024-03-01T12:12:00Z" }
  ],
  "hashChain": "0x9f3a...b7c2",
  "createdAt": "2024-03-01T12:00:00Z",
  "acceptedAt": "2024-03-01T12:12:00Z"
}

Error Codes

Status	Reason
404	Negotiation not found

POST/v1/negotiations/:id/respond

Respond to a negotiation with accept, reject, or counter-offer. Counter-offers include new proposed terms.

Request Body

{
  "action": "counter",
  "agentId": "agent-e5f6g7h8",
  "terms": {
    "amount": { "value": 4000, "currency": "USD" },
    "description": "Q1 data processing services (revised)"
  }
}

Response

{
  "id": "neg-k1l2m3n4",
  "status": "countered",
  "terms": {
    "amount": { "value": 4000, "currency": "USD" },
    "description": "Q1 data processing services (revised)"
  },
  "updatedAt": "2024-03-01T12:05:00Z"
}

Error Codes

Status	Reason
400	Invalid action type or missing terms for counter
403	Agent is not a participant in this negotiation
409	Negotiation is not in a respondable state