NAV Navigation

OASIS API v1.0.0

Scroll down for example requests and responses.

The Nimiq OASIS API provides a high-level interface to create Hashed Timelock Contracts (HTLCs) for arbitrary assets. It is intended to be implemented by an escrow party that can hold and transfer the supported asset types. The API is extensible with respect to which assets can be secured by the contract as well as how these assets are transferred. In its first instantiation, OASIS will work with Euro and the SEPA scheme for asset transfer. This document currently covers that specific instantiation only.

The Nimiq OASIS API is completely permissionless and as such can be used by client software running on an end-user's machine. None of its operations require authentication or prior registration.

Usage example

Assume a typical atomic swap scenario using HTLCs, where User A and User B wish to exchange assets. User A holds an asset escrowed by OASIS and User B holds an asset managed by another ledger (LEDGER). Interaction with the OASIS HTLC consists of four steps:

Base URLs:

Email: Nimiq Foundation, Inc. Web: Nimiq Foundation, Inc.

HTLC

Hash Time Locked Contract

prepare

POST /htlc

Prepares a new HTLC

Creates a new HTLC in the pending state and stores it in the OASIS database.

The HTLC does not hold any funds at this point and can be cleared (i.e. funded) using one of the clearing methods (e.g. SEPA transaction) provided in the clearing property.

The created HTLC is identified by a random id, which serves as an ad-hoc credential for further interaction with the contract.

Returns the created HashedTimeLockContract on success, a Problem otherwise.

Body parameter

{
  "asset": "EUR",
  "amount": 815.17,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z",
  "includeFee": false
}

Parameters

Name In Type Required Description
body body PrepareRequest true The HTLC to prepare

Example responses

200 OK

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "pending",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z",
  "clearing": {
    "status": "waiting",
    "options": [
      {
        "type": "sepa",
        "amount": 815.32,
        "recipient": {
          "name": "OASIS Escrow Bank",
          "iban": "DE33100300400411291302",
          "bic": "AAAADE99XXX"
        },
        "purpose": "HLCAZRQWYLDH4WTH22HEO2FCO"
      }
    ]
  }
}

400 Malformed JSON

{
  "type": "urn:x-oasis:problem:malformed-json",
  "status": 400,
  "title": "Malformed JSON"
}

400 Constraint violation

{
  "type": "urn:x-oasis:problem:constraint-violation",
  "status": 400,
  "title": "Constraint violation",
  "violations": [
    {
      "field": "amount",
      "message": "must have at most 2 decimal places"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK HashedTimeLockContract
400 Bad Request Bad Request Problem

get

GET /htlc/{id}

Fetches a single HTLC

Fetches a single HTLC by its id.

The properties clearing, settlement and preimage.value are populated depending on the state of the contract:

Parameters

Name In Type Required Description
id path string true ID of HTLC to fetch

Example responses

200 Pending HTLC

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "pending",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z",
  "clearing": {
    "status": "waiting",
    "options": [
      {
        "type": "sepa",
        "amount": 815.32,
        "recipient": {
          "name": "OASIS Escrow Bank",
          "iban": "DE33100300400411291302",
          "bic": "AAAADE99XXX"
        },
        "purpose": "HLCAZRQWYLDH4WTH22HEO2FCO"
      }
    ]
  }
}

200 Cleared HTLC

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "cleared",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z",
  "settlement": {
    "status": "waiting",
    "options": [
      {
        "type": "sepa"
      }
    ]
  }
}

200 Settled HTLC

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "settled",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32,
    "value": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI"
  },
  "expires": "2019-11-29T08:22:52Z",
  "settlement": {
    "status": "confirmed",
    "type": "sepa"
  }
}

200 Expired HTLC

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "expired",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z"
}

404 Not Found

{
  "type": "urn:x-oasis:problem:not-found",
  "status": 404,
  "title": "HTLC not found"
}

Responses

Status Meaning Description Schema
200 OK OK HashedTimeLockContract
404 Not Found Not Found Problem

settle

POST /htlc/{id}/settle

Settles a cleared HTLC

Settles the HTLC specified by id, transferring all funds held by it to the designated recipient if all of the following conditions are met:

Returns the updated HashedTimeLockContract on success, a Problem otherwise.

Body parameter

{
  "preimage": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI",
  "settlement": "eyJhbGciOiJFZERTQSIsImtpZCI6IiJ9.ewogICJ0eXBlIjogIm1vY2siLAogICJjb250cmFjdElkIjogIkhMQ0FaUlFXWUxESDRXVEgyMkhFTzJGQ08iCn0K.ikGoB3kHKVZb6pfKD7IrzY-SADQ4oSOG3cdVj-N7GKAOHvTeIvsCboOFsxT5eyzXUPlWLFnosUL0bH4WOyipCQ"
}

Parameters

Name In Type Required Description
id path string true ID of HTLC to settle
body body SettleRequest true Settle request

Example responses

200 OK

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "settled",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32,
    "value": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI"
  },
  "expires": "2019-11-29T08:22:52Z",
  "settlement": {
    "status": "pending",
    "type": "sepa"
  }
}

400 Malformed JSON

{
  "type": "urn:x-oasis:problem:malformed-json",
  "status": 400,
  "title": "Malformed JSON"
}

400 Constraint violation

{
  "type": "urn:x-oasis:problem:constraint-violation",
  "status": 400,
  "title": "Constraint violation",
  "violations": [
    {
      "field": "settlement",
      "message": "must be a Json Web Signature in compact serialization format"
    }
  ]
}

403 Invalid preimage

{
  "type": "urn:x-oasis:problem:htlc:invalid-preimage",
  "status": 403,
  "title": "Invalid preimage"
}

403 Invalid signature

{
  "type": "urn:x-oasis:problem:htlc:invalid-signature",
  "status": 403,
  "title": "Invalid signature"
}

404 Not Found

{
  "type": "urn:x-oasis:problem:not-found",
  "status": 404,
  "title": "HTLC not found"
}

409 Unexpected contract status

{
  "type": "urn:x-oasis:problem:htlc:unexpected-status",
  "status": 409,
  "title": "Unexpected contract status",
  "expected": "cleared",
  "actual": "expired"
}

Responses

Status Meaning Description Schema
200 OK OK HashedTimeLockContract
400 Bad Request Bad Request Problem
403 Forbidden Forbidden Problem
404 Not Found Not Found Problem
409 Conflict Conflict Problem

Mock

Mock engine for testing purposes

clear

POST /mock/clear/{id}

Clears a pending HTLC

Clears the HTLC specified by id, transitioning it into the cleared state.

This function is for testing purposes only and not available in production.

Parameters

Name In Type Required Description
id path string true ID of HTLC to clear

Example responses

404 Response

{
  "type": "urn:x-oasis:problem:not-found",
  "status": 404,
  "title": "HTLC not found"
}

409 Response

{
  "type": "urn:x-oasis:problem:htlc:unexpected-status",
  "status": 409,
  "title": "Unexpected contract status",
  "expected": "pending",
  "actual": "expired"
}

Responses

Status Meaning Description Schema
204 No Content No Content None
404 Not Found Not Found Problem
409 Conflict Conflict Problem

Schemas

AssetQuantity

815.17

Properties

Name Type Required Restrictions Description
anonymous number(float) false none none

AssetSymbol

"EUR"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous EUR

ClearingInfo

{
  "status": "waiting",
  "type": "sepa",
  "options": [
    {
      "type": "sepa"
    }
  ]
}

Properties

Name Type Required Restrictions Description
status ClearingStatus true none none
type string false none none
options [ClearingInstruction] false none [Abstract, implemented by SepaClearingInstruction, MockClearingInstruction.]

ClearingInstruction

{
  "type": "sepa"
}

Abstract, implemented by SepaClearingInstruction, MockClearingInstruction.

Properties

Name Type Required Restrictions Description
type ClearingType true none none

ClearingStatus

"waiting"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous waiting
anonymous partial
anonymous denied

ClearingType

"sepa"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous mock
anonymous sepa

ContractId

"HLCAZRQWYLDH4WTH22HEO2FCO"

Properties

Name Type Required Restrictions Description
anonymous string false none none

ContractStatus

"pending"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous pending
anonymous cleared
anonymous settled
anonymous expired

EllipticCurveKey

{
  "kty": "EC",
  "crv": "P-256",
  "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
}

Properties

allOf

Name Type Required Restrictions Description
anonymous JsonWebKey false none A JSON Web Key, one of EllipticCurveKey, OctetKeyPair.

and

Name Type Required Restrictions Description
anonymous object false none none
» crv string true none none
» x string(base64url) true none none
» y string(base64url) true none none

Enumerated Values

Property Value
crv P-256

Hash

{
  "algorithm": "sha256",
  "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
}

Properties

Name Type Required Restrictions Description
algorithm string true none none
value string(base64url) true none none

Enumerated Values

Property Value
algorithm sha256
algorithm sha512

HashedTimeLockContract

{
  "id": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "status": "pending",
  "asset": "EUR",
  "amount": 815.17,
  "fee": 0.15,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z",
  "clearing": {
    "status": "waiting",
    "options": [
      {
        "type": "sepa",
        "amount": 815.32,
        "recipient": {
          "name": "OASIS Escrow Bank",
          "iban": "DE33100300400411291302",
          "bic": "AAAADE99XXX"
        },
        "purpose": "HLCAZRQWYLDH4WTH22HEO2FCO"
      }
    ]
  }
}

Properties

Name Type Required Restrictions Description
id ContractId true none none
status ContractStatus true none none
asset AssetSymbol true none none
amount AssetQuantity true none none
fee AssetQuantity false none none
beneficiary JsonWebKey true none A JSON Web Key, one of EllipticCurveKey, OctetKeyPair.
hash Hash true none none
preimage Preimage true none none
expires string(date-time) true none none
clearing ClearingInfo false none none
settlement SettlementInfo false none none

JsonWebKey

{
  "kty": "EC"
}

A JSON Web Key, one of EllipticCurveKey, OctetKeyPair.

Properties

Name Type Required Restrictions Description
kty string true none none

Enumerated Values

Property Value
kty EC
kty OKP

MockClearingInstruction

{
  "type": "mock",
  "description": "POST to /mock/clear/{id} to clear contract"
}

Properties

allOf

Name Type Required Restrictions Description
anonymous ClearingInstruction false none Abstract, implemented by SepaClearingInstruction, MockClearingInstruction.

and

Name Type Required Restrictions Description
anonymous object false none none
» description string false none none

MockSettlementInstruction

{
  "type": "mock",
  "contractId": "HLCAZRQWYLDH4WTH22HEO2FCO"
}

Properties

None

OctetKeyPair

{
  "kty": "OKP",
  "crv": "Ed25519",
  "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
}

Properties

allOf

Name Type Required Restrictions Description
anonymous JsonWebKey false none A JSON Web Key, one of EllipticCurveKey, OctetKeyPair.

and

Name Type Required Restrictions Description
anonymous object false none none
» crv string true none none
» x string(base64url) true none none

Enumerated Values

Property Value
crv Ed25519

Preimage

{
  "size": 32,
  "value": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI"
}

Properties

Name Type Required Restrictions Description
size integer(int32) true none none
value string(base64url) false none none

PrepareRequest

{
  "asset": "EUR",
  "amount": 815.17,
  "beneficiary": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "D0mvLd04sBt6JnukPcOIq3ZUqxxbDn0VxY7TjiSTkPA"
  },
  "hash": {
    "algorithm": "sha256",
    "value": "Pyx8yumK-B5EwOxBlln1DYt9SMaB5dV_x0fQRh5C3aE"
  },
  "preimage": {
    "size": 32
  },
  "expires": "2019-11-29T08:22:52Z",
  "includeFee": false
}

Properties

Name Type Required Restrictions Description
asset AssetSymbol true none none
amount AssetQuantity true none none
beneficiary JsonWebKey true none A JSON Web Key, one of EllipticCurveKey, OctetKeyPair.
hash Hash true none none
preimage Preimage true none none
expires string(date-time) true none none
includeFee boolean false none If set to true, all fees are included in the specified amount (i.e. sender transfers amount, recipient receives amount - fees). If set to false, fees are added to the specified amount (i.e. sender transfers amount + fees, recipient receives amount).

Problem

{
  "type": "urn:x-oasis:problem:malformed-json",
  "title": "Malformed JSON",
  "status": 400
}

Properties

Name Type Required Restrictions Description
type string(uri) false none none
title string true none none
status integer(int32) true none none

SepaClearingInstruction

{
  "type": "sepa",
  "amount": 815.32,
  "recipient": {
    "name": "OASIS Escrow Bank",
    "iban": "DE33100300400411291302",
    "bic": "AAAADE99XXX"
  }
}

Properties

allOf

Name Type Required Restrictions Description
anonymous ClearingInstruction false none Abstract, implemented by SepaClearingInstruction, MockClearingInstruction.

and

Name Type Required Restrictions Description
anonymous object false none none
» amount AssetQuantity true none none
» recipient SepaRecipient true none none
» purpose string false none ID of the HTLC

SepaRecipient

{
  "name": "John Doe",
  "iban": "DE54500200200293291286",
  "bic": "AAAADE99XXX"
}

Properties

Name Type Required Restrictions Description
name string true none none
iban string(iban) true none none
bic string true none none

SepaSettlementInstruction

{
  "type": "sepa",
  "contractId": "HLCAZRQWYLDH4WTH22HEO2FCO",
  "recipient": {
    "name": "John Doe",
    "iban": "DE54500200200293291286",
    "bic": "AAAADE99XXX"
  }
}

Properties

allOf

Name Type Required Restrictions Description
anonymous SettlementInstruction false none Abstract, implemented by SepaSettlementInstruction, MockSettlementInstruction.

and

Name Type Required Restrictions Description
anonymous object false none none
» recipient SepaRecipient true none none

SettlementInfo

{
  "status": "confirmed",
  "type": "sepa",
  "options": [
    {
      "type": "sepa"
    }
  ]
}

Properties

Name Type Required Restrictions Description
status SettlementStatus true none none
type string false none none
options [SettlementDescriptor] false none none

SettlementStatus

"confirmed"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous waiting
anonymous pending
anonymous accepted
anonymous denied
anonymous confirmed
anonymous failed

SettlementType

"sepa"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous mock
anonymous sepa

SettlementDescriptor

{
  "type": "sepa"
}

Properties

Name Type Required Restrictions Description
type SettlementType true none none

SettlementInstruction

{
  "type": "sepa",
  "contractId": "HLCAZRQWYLDH4WTH22HEO2FCO"
}

Abstract, implemented by SepaSettlementInstruction, MockSettlementInstruction.

Properties

Name Type Required Restrictions Description
type SettlementType true none none
contractId ContractId true none none

SettleRequest

{
  "preimage": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI",
  "settlement": "eyJhbGciOiJFZERTQSIsImtpZCI6IiJ9.ewogICJ0eXBlIjogIm1vY2siLAogICJjb250cmFjdElkIjogIkhMQ0FaUlFXWUxESDRXVEgyMkhFTzJGQ08iCn0K.ikGoB3kHKVZb6pfKD7IrzY-SADQ4oSOG3cdVj-N7GKAOHvTeIvsCboOFsxT5eyzXUPlWLFnosUL0bH4WOyipCQ"
}

Properties

Name Type Required Restrictions Description
preimage string(base64url) true none The HTLC preimage
settlement string true none A JSON Web Signature in compact serialization format. The signed payload is a SettlementInstruction (e.g. SepaSettlementInstruction).