Skip to main content

Swap Endpoint

Swap secrets between deeds to transfer ownership, split tokens, or secure custody.

Endpoint​

POST /v1/swap

Purpose​

Swap secrets between deeds. The server will only complete the swap if the hash of the secrets provided in the inputs match the hashes it has stored.

Request Body​

{
  "inputs": ["+100.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.oldsecret"],
  "outputs": ["+100.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.newsecret"]
}

Parameters​

  • inputs (required)

    • Type: array of strings
    • Format: Each string should follow the format: 
      +[[amount]].[[itemID]].[[secret]]
    • Description: The input deeds you want to swap, including their secrets.

  • outputs (required)

    • Type: array of strings
    • Format: Each string should follow the format: 
      +[[amount]].[[itemID]].[[secret]]
    • Description: The output deeds you want to create, with new secrets.

Response​

Success Response (200 OK)​

{
  "success": true
}

Error Response (400 Bad Request)​

Returned if the request is invalid or if the input secrets do not match the server's stored hashes.

Examples​

Simple Secret Update​

This example shows how to update the secret of a deed, which is required when taking custody of a deed after receiving it.

Request​

{
  "inputs": ["+100.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.oldsecret"],
  "outputs": ["+100.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.newsecret"]
}

Response​

{
  "success": true
}

Splitting a Deed​

This example shows how to split a 100-unit deed into a 10-unit and a 90-unit deed.

Request​

{
  "inputs": ["+100.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.original_secret"],
  "outputs": [
    "+10.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.new_secret_for_10",
    "+90.deed_2samLx0gNPgbb6o3JxKMSWSzz3E.new_secret_for_90"
  ]
}

Response​

{
  "success": true
}

Important Notes​

  • The sum of the amounts in the outputs must equal the sum of the amounts in the inputs.
  • The server verifies that the hash of each input secret matches what was previously stored.
  • After receiving a deed from someone else, you should immediately perform a swap to update the secret to one only you know.