Handshake

GET/api/v1/handshake/{domain}/sessions

List_sessions

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: updated_at, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

mine?boolean

Only return sessions where the caller is a party

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/handshake/string/sessions"

{  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "sessions": [    {      "active_offer_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "domain": "string",      "initiator": {        "id": "string",        "kind": "auth_user",        "label": "string"      },      "policy": {        "max_rounds": 0,        "offer_ttl_seconds": 0,        "session_ttl_seconds": 0,        "settlement_timeout_seconds": 0      },      "responder": {        "id": "string",        "kind": "auth_user",        "label": "string"      },      "round": 0,      "session_id": "string",      "settlement_id": "string",      "status": "NEGOTIATING",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

POST/api/v1/handshake/{domain}/sessions

Create_session

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

counterparty_id*string

Identifier of the counterparty (user id or agent id)

counterparty_kind*PartyKind

Kind of counterparty (auth_user or agent)

Value in

"auth_user"
"agent"

counterparty_label?|

Optional human-readable label for the counterparty

metadata?unknown

Optional metadata

opening_offer?null|

policy?

Optional policy overrides

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions" \  -H "Content-Type: application/json" \  -d '{    "counterparty_id": "string",    "counterparty_kind": "auth_user"  }'

{  "opening_offer": null,  "session": {    "active_offer_id": "string",    "created_at": "2019-08-24T14:15:22Z",    "domain": "string",    "initiator": {      "id": "string",      "kind": "auth_user",      "label": "string"    },    "policy": {      "max_rounds": 0,      "offer_ttl_seconds": 0,      "session_ttl_seconds": 0,      "settlement_timeout_seconds": 0    },    "responder": {      "id": "string",      "kind": "auth_user",      "label": "string"    },    "round": 0,    "session_id": "string",    "settlement_id": "string",    "status": "NEGOTIATING",    "updated_at": "2019-08-24T14:15:22Z"  }}

GET/api/v1/handshake/{domain}/sessions/{id}

Get_session

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/handshake/string/sessions/string"

{  "active_offer_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "domain": "string",  "initiator": {    "id": "string",    "kind": "auth_user",    "label": "string"  },  "policy": {    "max_rounds": 0,    "offer_ttl_seconds": 0,    "session_ttl_seconds": 0,    "settlement_timeout_seconds": 0  },  "responder": {    "id": "string",    "kind": "auth_user",    "label": "string"  },  "round": 0,  "session_id": "string",  "settlement_id": "string",  "status": "NEGOTIATING",  "updated_at": "2019-08-24T14:15:22Z"}

POST/api/v1/handshake/{domain}/sessions/{id}/cancel

Cancel_session

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/cancel"

{  "message": "string",  "rolled_back": true,  "session_id": "string"}

GET/api/v1/handshake/{domain}/sessions/{id}/history

Get_history

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: created_at, round. Default: round.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

view?string

View mode: "transcript" (default) or "concessions"

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/handshake/string/sessions/string/history"

{  "concessions": [    {      "deltas": [        {          "currency_deltas": [            {              "currency_id": "string",              "delta": 0.1            }          ],          "items_added": [            "string"          ],          "items_removed": [            "string"          ],          "party_id": "string",          "terms_changed": [            "string"          ]        }      ],      "round": 0    }  ],  "offers": [    {      "bundle": {        "initiator_gives": {          "currency_legs": [            {              "amount": 0.1,              "currency_id": "string"            }          ],          "item_legs": [            {              "item_id": "string",              "quantity": 0            }          ],          "terms": [            {              "binding": true,              "key": "string",              "value": "string"            }          ]        },        "responder_gives": {          "currency_legs": [            {              "amount": 0.1,              "currency_id": "string"            }          ],          "item_legs": [            {              "item_id": "string",              "quantity": 0            }          ],          "terms": [            {              "binding": true,              "key": "string",              "value": "string"            }          ]        }      },      "created_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "in_reply_to": "string",      "offer_id": "string",      "proposed_by": "string",      "round": 0,      "session_id": "string",      "status": "OPEN"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "session_id": "string",  "view": "string"}

POST/api/v1/handshake/{domain}/sessions/{id}/offers

Submit_offer

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

bundle*

The proposed bundle for this offer or counteroffer

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/offers" \  -H "Content-Type: application/json" \  -d '{    "bundle": {      "initiator_gives": {},      "responder_gives": {}    }  }'

{  "bundle": {    "initiator_gives": {      "currency_legs": [        {          "amount": 0.1,          "currency_id": "string"        }      ],      "item_legs": [        {          "item_id": "string",          "quantity": 0        }      ],      "terms": [        {          "binding": true,          "key": "string",          "value": "string"        }      ]    },    "responder_gives": {      "currency_legs": [        {          "amount": 0.1,          "currency_id": "string"        }      ],      "item_legs": [        {          "item_id": "string",          "quantity": 0        }      ],      "terms": [        {          "binding": true,          "key": "string",          "value": "string"        }      ]    }  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "in_reply_to": "string",  "offer_id": "string",  "proposed_by": "string",  "round": 0,  "session_id": "string",  "status": "OPEN"}

POST/api/v1/handshake/{domain}/sessions/{id}/offers/{offer_id}/accept

Accept_offer

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

offer_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/offers/string/accept"

{  "accepted_offer_id": "string",  "deadline_at": "2019-08-24T14:15:22Z",  "initiator_stage": {    "confirmed": true,    "item_lock_ids": [      "string"    ],    "ledger_hold_ids": [      "string"    ],    "party_id": "string",    "staged": true  },  "responder_stage": {    "confirmed": true,    "item_lock_ids": [      "string"    ],    "ledger_hold_ids": [      "string"    ],    "party_id": "string",    "staged": true  },  "session_id": "string",  "settlement_id": "string",  "status": "STAGING"}

POST/api/v1/handshake/{domain}/sessions/{id}/offers/{offer_id}/reject

Reject_offer

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

offer_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/offers/string/reject"

{  "bundle": {    "initiator_gives": {      "currency_legs": [        {          "amount": 0.1,          "currency_id": "string"        }      ],      "item_legs": [        {          "item_id": "string",          "quantity": 0        }      ],      "terms": [        {          "binding": true,          "key": "string",          "value": "string"        }      ]    },    "responder_gives": {      "currency_legs": [        {          "amount": 0.1,          "currency_id": "string"        }      ],      "item_legs": [        {          "item_id": "string",          "quantity": 0        }      ],      "terms": [        {          "binding": true,          "key": "string",          "value": "string"        }      ]    }  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "in_reply_to": "string",  "offer_id": "string",  "proposed_by": "string",  "round": 0,  "session_id": "string",  "status": "OPEN"}

POST/api/v1/handshake/{domain}/sessions/{id}/offers/{offer_id}/withdraw

Withdraw_offer

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

offer_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/offers/string/withdraw"

{  "bundle": {    "initiator_gives": {      "currency_legs": [        {          "amount": 0.1,          "currency_id": "string"        }      ],      "item_legs": [        {          "item_id": "string",          "quantity": 0        }      ],      "terms": [        {          "binding": true,          "key": "string",          "value": "string"        }      ]    },    "responder_gives": {      "currency_legs": [        {          "amount": 0.1,          "currency_id": "string"        }      ],      "item_legs": [        {          "item_id": "string",          "quantity": 0        }      ],      "terms": [        {          "binding": true,          "key": "string",          "value": "string"        }      ]    }  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "in_reply_to": "string",  "offer_id": "string",  "proposed_by": "string",  "round": 0,  "session_id": "string",  "status": "OPEN"}

POST/api/v1/handshake/{domain}/sessions/{id}/settlement/confirm

Confirm_settlement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

staged_state_hash?|

The hash of the fully staged state this confirmation binds to

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/settlement/confirm" \  -H "Content-Type: application/json" \  -d '{}'

{  "outcome": "WAITING_FOR_COUNTERPARTY",  "settlement": {    "accepted_offer_id": "string",    "deadline_at": "2019-08-24T14:15:22Z",    "initiator_stage": {      "confirmed": true,      "item_lock_ids": [        "string"      ],      "ledger_hold_ids": [        "string"      ],      "party_id": "string",      "staged": true    },    "responder_stage": {      "confirmed": true,      "item_lock_ids": [        "string"      ],      "ledger_hold_ids": [        "string"      ],      "party_id": "string",      "staged": true    },    "session_id": "string",    "settlement_id": "string",    "status": "STAGING"  }}

POST/api/v1/handshake/{domain}/sessions/{id}/settlement/stage

Stage_settlement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/sessions/string/settlement/stage"

{  "accepted_offer_id": "string",  "deadline_at": "2019-08-24T14:15:22Z",  "initiator_stage": {    "confirmed": true,    "item_lock_ids": [      "string"    ],    "ledger_hold_ids": [      "string"    ],    "party_id": "string",    "staged": true  },  "responder_stage": {    "confirmed": true,    "item_lock_ids": [      "string"    ],    "ledger_hold_ids": [      "string"    ],    "party_id": "string",    "staged": true  },  "session_id": "string",  "settlement_id": "string",  "status": "STAGING"}

POST/api/v1/handshake/{domain}/settlements/sweep

Sweep_settlements

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

domain*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/handshake/string/settlements/sweep"

{  "cancelled": 0,  "message": "string"}

Handshake

200application/json

400

503

201application/json

400

503

200application/json

403

404

503

200application/json

403

404

409

503

200application/json

400

403

404

503

201application/json

403

404

409

503

200application/json

403

404

409

503

200application/json

403

404

409

503

200application/json

403

404

409

503

200application/json

403

404

409

503

200application/json

403

404

409

503

200application/json

403

503

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`