Bitcoin Attestation Protocol API v0.1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

API for getting information from the Bitcoin BAP network. All the API calls are POST only, to preserve privacy and prevent easy logging of getting attestation by web servers.

NOTE: Only well formed and properly signed BAP transactions will be included in this API.

For more information about BAP please see https://github.com/icellan/bap

For the markdown documentation, see: /bap-api.md

For the API YAML definition, see: /bap-api.yaml

Want to run your own indexer or API? Check out https://github.com/icellan/bap-planaria

Base URLs:

• /v1

• //bap-api.com/v1

License: Open BSV license

free & pro

Bitcoin Attestation Protocol API

getAttestation

Code samples

POST /v1/attestation/get HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /attestation/get

Get an attestation by hash value

Body parameter

{
  "hash": "b17c8e606afcf0d8dca65bdf8f33d275239438116557980203c82b0fae259838"
}

Parameters

Name	In	Type	Required	Description
body	body	AttestationGetParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "hash": "b17c8e606afcf0d8dca65bdf8f33d275239438116557980203c82b0fae259838",
    "signers": [
      {
        "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "1fd626dc8286d449d4c2cf3b5b70d169728f5ffefd5c3a3205d4970e21fbf187",
        "block": 590230,
        "sequence": 0
      }
    ]
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Attestation could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	AttestationGetResponse
404	Not Found	ERROR	ErrorResponse

getIdentity

Code samples

POST /v1/identity/get HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /identity/get

Get an identity record by idKey

Body parameter

{
  "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f"
}

Parameters

Name	In	Type	Required	Description
body	body	IdentityGetParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
    "firstSeen": 590194,
    "rootAddress": "18nBpQeLxQpnvnZninJbbtGHgY7ru6Mboa",
    "currentAddress": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
    "addresses": [
      {
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "aa9670f44439c45db24daa5d084021b6667ff317a550d3a5671f564fac4d724c",
        "block": 590194
      }
    ]
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Identity could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	IdentityGetResponse
404	Not Found	ERROR	ErrorResponse

getIdentityByAddress

Code samples

POST /v1/identity/getByAddress HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /identity/getByAddress

Get an identity record by signing address

Body parameter

{
  "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da"
}

Parameters

Name	In	Type	Required	Description
body	body	IdentityGetByAddressParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
    "firstSeen": 590194,
    "rootAddress": "18nBpQeLxQpnvnZninJbbtGHgY7ru6Mboa",
    "currentAddress": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
    "addresses": [
      {
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "aa9670f44439c45db24daa5d084021b6667ff317a550d3a5671f564fac4d724c",
        "block": 590194
      }
    ]
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Identity could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	IdentityGetByAddressResponse
404	Not Found	ERROR	ErrorResponse

getDid

Code samples

POST /v1/identity/did HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /identity/did

Get the DID of an identity record by idKey

Body parameter

{
  "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f"
}

Parameters

Name	In	Type	Required	Description
body	body	IdentityGetParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "@context": [
      "https://w3id.org/did/v0.11",
      "https://w3id.org/bap/v1"
    ],
    "id": "did:bap:id:3SyWUZXvhidNcEHbAC3HkBnKoD2Q",
    "publicKey": [
      {
        "id": "did:bitcoin:tx:f575517994815862e75b3ab61b80a5c4c5a02c3720a246d83c4eccad28576fe3#root",
        "controller": "did:bap:id:3SyWUZXvhidNcEHbAC3HkBnKoD2Q",
        "type": "EcdsaSecp256k1VerificationKey2019",
        "bitcoinAddress": "1WffojxvgpQBmUTigoss7VUdfN45JiiRK"
      },
      {
        "id": "did:bitcoin:tx:e2cd5e96b985af9314559f3ff6a7919dd5358e986edcdb912fe1028b565890da#key1",
        "controller": "did:bap:id:3SyWUZXvhidNcEHbAC3HkBnKoD2Q",
        "type": "EcdsaSecp256k1VerificationKey2019",
        "bitcoinAddress": "1K4c6YXR1ixNLAqrL8nx5HUQAPKbACTwDo"
      }
    ],
    "authentication": [
      "#key1"
    ],
    "assertionMethod": [
      "#key1"
    ]
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Identity could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	IdentityDidResponse
404	Not Found	ERROR	ErrorResponse

getDidByAddress

Code samples

POST /v1/identity/didByAddress HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /identity/didByAddress

Get the DID of an identity by signing address

Body parameter

{
  "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da"
}

Parameters

Name	In	Type	Required	Description
body	body	IdentityGetByAddressParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "@context": [
      "https://w3id.org/did/v0.11",
      "https://w3id.org/bap/v1"
    ],
    "id": "did:bap:id:3SyWUZXvhidNcEHbAC3HkBnKoD2Q",
    "publicKey": [
      {
        "id": "did:bitcoin:tx:f575517994815862e75b3ab61b80a5c4c5a02c3720a246d83c4eccad28576fe3#root",
        "controller": "did:bap:id:3SyWUZXvhidNcEHbAC3HkBnKoD2Q",
        "type": "EcdsaSecp256k1VerificationKey2019",
        "bitcoinAddress": "1WffojxvgpQBmUTigoss7VUdfN45JiiRK"
      },
      {
        "id": "did:bitcoin:tx:e2cd5e96b985af9314559f3ff6a7919dd5358e986edcdb912fe1028b565890da#key1",
        "controller": "did:bap:id:3SyWUZXvhidNcEHbAC3HkBnKoD2Q",
        "type": "EcdsaSecp256k1VerificationKey2019",
        "bitcoinAddress": "1K4c6YXR1ixNLAqrL8nx5HUQAPKbACTwDo"
      }
    ],
    "authentication": [
      "#key1"
    ],
    "assertionMethod": [
      "#key1"
    ]
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Identity could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	IdentityDidResponse
404	Not Found	ERROR	ErrorResponse

pro

Bitcoin Attestation Protocol API pro only

validAttestation

Code samples

POST /v1/attestation/valid HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /attestation/valid

Check whether the given attestation is valid and return all attesters that signed. If block are timestamp is not given, check for current time.

Body parameter

{
  "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
  "attribute": "name",
  "value": "John Doe",
  "nonce": "e2c6fb4063cc04af58935737eaffc938011dff546d47b7fbb18ed346f8c4d4fa"
}

Parameters

Name	In	Type	Required	Description
body	body	AttestationValidParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "attribute": "name",
    "value": "John Doe",
    "nonce": "e2c6fb4063cc04af58935737eaffc938011dff546d47b7fbb18ed346f8c4d4fa",
    "urn": "urn:bap:id:name:John Doe:e2c6fb4063cc04af58935737eaffc938011dff546d47b7fbb18ed346f8c4d4fa",
    "hash": "b17c8e606afcf0d8dca65bdf8f33d275239438116557980203c82b0fae259838",
    "signers": [
      {
        "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "1fd626dc8286d449d4c2cf3b5b70d169728f5ffefd5c3a3205d4970e21fbf187",
        "block": 590230,
        "sequence": 0
      }
    ],
    "block": 594320,
    "timestamp": 1565040382,
    "valid": true
  }
}

{
  "status": "OK",
  "result": {
    "hash": "b17c8e606afcf0d8dca65bdf8f33d275239438116557980203c82b0fae259838",
    "signers": [
      {
        "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "1fd626dc8286d449d4c2cf3b5b70d169728f5ffefd5c3a3205d4970e21fbf187",
        "block": 590230,
        "sequence": 0
      }
    ],
    "block": 594320,
    "timestamp": 1565040382,
    "valid": true
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Attestation could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	AttestationValidResponse
404	Not Found	ERROR	ErrorResponse

validIdentity

Code samples

POST /v1/identity/valid HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /identity/valid

Check whether the given identity and signing address is valid and return all addresses that are valid for signing. If block are timestamp is not given, check for current time.

Body parameter

{
  "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
  "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da"
}

Parameters

Name	In	Type	Required	Description
body	body	IdentityValidParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
    "firstSeen": 590194,
    "rootAddress": "18nBpQeLxQpnvnZninJbbtGHgY7ru6Mboa",
    "currentAddress": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
    "addresses": [
      {
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "aa9670f44439c45db24daa5d084021b6667ff317a550d3a5671f564fac4d724c",
        "block": 590194
      }
    ],
    "block": 594320,
    "timestamp": 1565040382,
    "valid": true
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Identity could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	IdentityValidResponse
404	Not Found	ERROR	ErrorResponse

validIdentityByAddress

Code samples

POST /v1/identity/validByAddress HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /identity/validByAddress

Check whether the given address belongs to an identity and is valid, and return all addresses that are valid for signing. If block are timestamp is not given, check for current time.

Body parameter

{
  "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da"
}

Parameters

Name	In	Type	Required	Description
body	body	IdentityValidByAddressParams	true	none

Example responses

OK

{
  "status": "OK",
  "result": {
    "idKey": "714a3c856435781fb48ca16a4cf0ba9bc1ef16dd7abbc060d3e18e7e900eec9f",
    "firstSeen": 590194,
    "rootAddress": "18nBpQeLxQpnvnZninJbbtGHgY7ru6Mboa",
    "currentAddress": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
    "addresses": [
      {
        "address": "134a6TXxzgQ9Az3w8BcvgdZyA5UqRL89da",
        "txId": "aa9670f44439c45db24daa5d084021b6667ff317a550d3a5671f564fac4d724c",
        "block": 590194
      }
    ],
    "block": 594320,
    "timestamp": 1565040382,
    "valid": true
  }
}

ERROR

{
  "status": "ERROR",
  "message": "Identity could not be found"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	IdentityValidByAddressResponse
404	Not Found	ERROR	ErrorResponse

Schemas

ErrorResponse

{
  "status": "string",
  "message": "string"
}

Error Response

Properties

Name	Type	Required	Restrictions	Description
status	string	false	none	none
message	string	false	none	none

Signers

{
  "idKey": "stringstringstringstringst",
  "address": "stringstringstringstringst",
  "txId": "stringstringstringstringstringstringstringstringstringstringstri",
  "block": 0,
  "sequence": 0
}

Attestation Signers

Properties

Name	Type	Required	Restrictions	Description
idKey	string	true	none	Identity key of the attester
address	string	false	none	Address the identiy that signed the attestation
txId	string	false	none	Transaction ID of the attestation
block	number	false	none	BLock the transaction was mined
sequence	number	false	none	Sequence number of the attestation for the signing identity

Addresses

{
  "address": "stringstringstringstringst",
  "txId": "stringstringstringstringstringstringstringstringstringstringstri",
  "block": 0
}

Identity signing addresses

Properties

Name	Type	Required	Restrictions	Description
address	string	false	none	Address the identity could sign with
txId	string	false	none	Transaction ID of the address introduction
block	number	false	none	BLock of the address introduction

AttestationRecord

{
  "attribute": "string",
  "value": "string",
  "nonce": "stringstringstringstringstringstringstringstringstringstringstri",
  "urn": "string",
  "hash": "stringstringstringstringstringstringstringstringstringstringstri",
  "signers": [
    {
      "idKey": "stringstringstringstringst",
      "address": "stringstringstringstringst",
      "txId": "stringstringstringstringstringstringstringstringstringstringstri",
      "block": 0,
      "sequence": 0
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
attribute	string	false	none	The attribute of the attestation
value	string	false	none	The value of the attribute of the attestation
nonce	string	false	none	The nonce of the attestation
urn	string	false	none	Attestation urn
hash	string	false	none	Attestation hash
signers	[Signers]	false	none	Array of all identities that signed the attestation

DIDKeys

{
  "id": "string",
  "controller": "string",
  "type": "EcdsaSecp256k1VerificationKey2019",
  "bitcoinAddress": "stringstringstringstringst"
}

Identity keys of a DID

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The Bitcoin tx id the key was published
controller	string	true	none	The id of the DID
type	string	true	none	The type of key
bitcoinAddress	string	true	none	The address of the key

IdentityRecord

{
  "idKey": "stringstringstringstringstringstringstringstringstringstringstri",
  "firstSeen": 0,
  "rootAddress": "stringstringstringstringst",
  "currentAddress": "stringstringstringstringst",
  "addresses": [
    {
      "address": "stringstringstringstringst",
      "txId": "stringstringstringstringstringstringstringstringstringstringstri",
      "block": 0
    }
  ]
}

Identity record

Properties

Name	Type	Required	Restrictions	Description
idKey	string	false	none	Attestation hash
firstSeen	number	false	none	Block this identity was first seen
rootAddress	string	false	none	Bitcoin root address of this identity
currentAddress	string	false	none	Current Bitcoin address this identity will sign with
addresses	[Addresses]	false	none	Array of all addresses this identity could ever signed with

IdentityDidRecord

{
  "@context": [
    "string"
  ],
  "id": "string",
  "publicKey": [
    {
      "id": "string",
      "controller": "string",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "bitcoinAddress": "stringstringstringstringst"
    }
  ],
  "authentication": [
    "string"
  ],
  "assertionMethod": [
    "string"
  ]
}

Identity DID record

Properties

Name	Type	Required	Restrictions	Description
@context	[string]	false	none	DID context
id	string	false	none	The BAP ID of this DID (did:bap🆔[idKey]])
publicKey	[DIDKeys]	false	none	The signing keys for this identity
authentication	[string]	false	none	The current address to use for authentication
assertionMethod	[string]	false	none	The current address to use for assertions

ValidityRecord

{
  "block": 0,
  "timestamp": "stringstringstringstringstringstringstringstringstringstringstri",
  "valid": true
}

Properties

Name	Type	Required	Restrictions	Description
block	number	false	none	The block the attestation and the signature of the identity should be valid
timestamp	string	false	none	Time the attestation and the signature of the identity should be valid
valid	boolean	false	none	whether the attestation is valid

AttestationGetParams

{
  "hash": "stringstringstringstringstringstringstringstringstringstringstri"
}

POST format for /attestation/get

Properties

Name	Type	Required	Restrictions	Description
hash	string	true	none	The hash of the attestation

AttestationGetResponse

null

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	AttestationRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

AttestationValidParams

{
  "attribute": "string",
  "value": "string",
  "nonce": "stringstringstringstringstringstringstringstringstringstringstri",
  "urn": "string",
  "hash": "stringstringstringstringstringstringstringstringstringstringstri",
  "block": 0,
  "timestamp": 0
}

POST format for /attestation/valid

Properties

Name	Type	Required	Restrictions	Description
attribute	string	false	none	The attribute of the attestation
value	string	false	none	The value of the attribute of the attestation
nonce	string	false	none	The nonce of the attestation
urn	string	false	none	The urn of the attestation
hash	string	false	none	The hash of the attestation
block	number	false	none	The block the attestation and the signature of the identity should be valid
timestamp	number	false	none	Time the attestation and the signature of the identity should be valid

AttestationValidResponse

null

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	AttestationRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	ValidityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

IdentityGetParams

{
  "idKey": "stringstringstringstringst"
}

POST format for /identity/get

Properties

Name	Type	Required	Restrictions	Description
idKey	string	true	none	The identity key of the identity

IdentityGetResponse

{
  "idKey": "stringstringstringstringstringstringstringstringstringstringstri",
  "firstSeen": 0,
  "rootAddress": "stringstringstringstringst",
  "currentAddress": "stringstringstringstringst",
  "addresses": [
    {
      "address": "stringstringstringstringst",
      "txId": "stringstringstringstringstringstringstringstringstringstringstri",
      "block": 0
    }
  ]
}

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	IdentityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

IdentityDidResponse

{
  "@context": [
    "string"
  ],
  "id": "string",
  "publicKey": [
    {
      "id": "string",
      "controller": "string",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "bitcoinAddress": "stringstringstringstringst"
    }
  ],
  "authentication": [
    "string"
  ],
  "assertionMethod": [
    "string"
  ]
}

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	IdentityDidRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

IdentityGetByAddressParams

{
  "address": "stringstringstringstringst"
}

POST format for /identity/getByAddress

Properties

Name	Type	Required	Restrictions	Description
address	string	true	none	Address the identity could sign with

IdentityGetByAddressResponse

{
  "idKey": "stringstringstringstringstringstringstringstringstringstringstri",
  "firstSeen": 0,
  "rootAddress": "stringstringstringstringst",
  "currentAddress": "stringstringstringstringst",
  "addresses": [
    {
      "address": "stringstringstringstringst",
      "txId": "stringstringstringstringstringstringstringstringstringstringstri",
      "block": 0
    }
  ]
}

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	IdentityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

IdentityValidParams

{
  "idKey": "stringstringstringstringst",
  "address": "stringstringstringstringst",
  "block": 0,
  "timestamp": 0
}

POST format for /identity/valid

Properties

Name	Type	Required	Restrictions	Description
idKey	string	true	none	The identity key of the identity
address	string	true	none	The address of the identity
block	number	false	none	The block the address of the identity should be valid
timestamp	number	false	none	The timestamp the address of the identity should be valid

IdentityValidResponse

{
  "idKey": "stringstringstringstringstringstringstringstringstringstringstri",
  "firstSeen": 0,
  "rootAddress": "stringstringstringstringst",
  "currentAddress": "stringstringstringstringst",
  "addresses": [
    {
      "address": "stringstringstringstringst",
      "txId": "stringstringstringstringstringstringstringstringstringstringstri",
      "block": 0
    }
  ],
  "block": 0,
  "timestamp": "stringstringstringstringstringstringstringstringstringstringstri",
  "valid": true
}

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	IdentityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	ValidityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none

IdentityValidByAddressParams

{
  "address": "stringstringstringstringst",
  "block": 0,
  "timestamp": 0
}

POST format for /identity/validByAddress

Properties

Name	Type	Required	Restrictions	Description
address	string	true	none	The address of the identity
block	number	false	none	The block the address of the identity should be valid
timestamp	number	false	none	The timestamp the address of the identity should be valid

IdentityValidByAddressResponse

{
  "idKey": "stringstringstringstringstringstringstringstringstringstringstri",
  "firstSeen": 0,
  "rootAddress": "stringstringstringstringst",
  "currentAddress": "stringstringstringstringst",
  "addresses": [
    {
      "address": "stringstringstringstringst",
      "txId": "stringstringstringstringstringstringstringstringstringstringstri",
      "block": 0
    }
  ],
  "block": 0,
  "timestamp": "stringstringstringstringstringstringstringstringstringstringstri",
  "valid": true
}

Properties

allOf

Name	Type	Required	Restrictions	Description
anonymous	IdentityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	ValidityRecord	false	none	none

and

Name	Type	Required	Restrictions	Description
anonymous	any	false	none	none