Phone number to address API Reference

This is the PhoneNumberToAddress (pn2a) API to link a verified phone number to an address. The verification happens through a secret code sent with an SMS. This API is described with OpenAPI.

If your library have https problem with the endpoint https://api.eternitywall.com (let's encrypt certificate) try: https://eternitywall-api.appspot.com

The test endpoint of the library is: https://eternitywall-api-test.appspot.com

API Endpoint
https://api.eternitywall.com/pn2a/v1
Contact: api@eternitywall.com
Schemes: https
Version: 0.1.0

Authentication

apikey

description

This is a static api key

name
api_key
in
header

signature

description

The used signature is the bitcoin message signature. What is being signed is specified in the relative method description.

name
x-signature
in
header

Paths

POST /sendsms/{number}

Send SMS to {number} with a code to verify

number

The mobile phone number to verify, it's a string containing only number and the international prefix code

type
string
in
path
200 OK

The possible outcome is "sent" meaning the server sent the SMS to {number}. If the SMS is already been sent recently, it will return already sent (code=1)

400 Bad Request

Bad input parameters

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "ok",
  "message": "message sent!",
  "code": 0
}

POST /verify/{number}

This method verify the {secret_code} sent via SMS with a previous call to /sendsms/{number} match the one provided. If this happen the {genesis_address} of this phone is saved.

number

The mobile number to verify

type
string
in
path
secret_code

The secret code received by SMS

type
string
in
formData
genesis_address

The genesis address linked to the phone number

type
string
in
formData
xpub

The xpub linked to the phone number

type
string
in
formData
200 OK

successful operation, or unsuccesfull if secret code doesn't match (code=2)

400 Bad Request

Bad input parameters

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "ko",
  "message": "secret code does not match",
  "code": 2
}

GET /address/{number}

this methods return the {address} of the owner of {number}. The address returned will be the last updated by the owner through this same endpoint with POST, or if the xpub is set in the method /verify/{number} will return the first derivation wich is not used in the blockchain.

number

The mobile {number} of the user whom I requesting the {address}

type
string
in
path
200 OK

successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "ok",
  "value": {
    "number": "00393291234567",
    "address": "n1o1Pqt2sCNwKiY5eYx5HXoFXn7VKcefXi"
  },
  "code": 0
}

POST /address/{number}

This method update the current {address} of {number}, to avoid unauthorized updates it require authentication of the user obtained with a {signature} of the new {address} with the {genesis_address} private key

number

The mobile number of which I want to update the address

type
string
in
path
new_address

The new address

type
string
in
formData
200 OK

Successful operation

400 Bad Request

Bad input parameters

401 Unauthorized

Unauthorized, signature not verified

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "ok",
  "message": "Everything is ok!",
  "code": 0,
  "value": {}
}

POST /addresses

this methods return addresses in bulk given phone numbers

numbers

this are the phone numbers to lookup for addresses

type
string[]
in
formData
200 OK

successful operation

Response Content-Types: application/json, application/xml
Response Example (200 OK)
{
  "status": "ok",
  "value": {
    "numbers": [
      {
        "number": "00393295555555",
        "address": "n1o1Pqt2sCNwKiY5eYx5HXoFXn7VKcefXi"
      },
      {
        "number": "00413335555555",
        "address": "n1WX9q5ACfEJxu1KRJSNVHLZxVBHage5Nj"
      }
    ]
  },
  "code": 0
}

POST /iban/verify

This method verify the {secret_code} sent via SMS with a previous call to /sendsms/{number} match the one provided. If this happen the phone_number_hash, iban_hash, and public_key_hash are saved for retriveal with /iban/ibanh/*

phone_number_hash

The phone number hash

type
string
in
formData
secret_code

The sected code received through sms

type
int
in
formData
iban_hash

The hash of the recipient iban

type
string
in
formData
public_key_hash

The public key hash of the sender

type
string
in
formData
200 OK

successful operation, or unsuccesfull if secret code doesn't match (code=2)

400 Bad Request

Bad input parameters

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "ko",
  "message": "secret code does not match",
  "code": 2
}

GET /iban/get/{public_key_hash}

this methods return the {iban_hash} sent from the owner of {public_key_hash}.

public_key_hash

The {public_key_hash} of the user sending to iban

type
string
in
path
200 OK

successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "ok",
  "value": {
    "ibans": [
      {
        "phoneNumberHash": "7A557D06253A7959CCD7B5E73582A708ACFB7EDF8AC0340D70F1653CB5048BD5",
        "ibanHash": "7A557D06253A7959CCD7B5E73582A708ACFB7EDF8AC0340D70F1653CB5048BD5",
        "publicKeyHash": "n1o1Pqt2sCNwKiY5eYx5HXoFXn7VKcefXi"
      }
    ]
  },
  "code": 0
}

Schema Definitions

Number: string

A telephone number with the international prefix

Result: object

status: string ok, ko
message: string

a human readable message

code: integer (int32)

a number representing the status, if 0 is ok otherwise it depends on the method

value: object
Example
{
  "status": "ok",
  "message": "Everything is ok!",
  "code": 0,
  "value": {}
}