NAV
shell

BVAM Provider API

Welcome to the BVAM Provider API.

You can use the public API to upload new BVAM. For more about Blockchain Validated Asset Metadata, see https://github.com/CounterpartyXCP/cips/blob/master/cip-0007.md.

All API calls begin with https://bvam.tokenly.com.

BVAM API Methods

Adds and validates a temporary BVAM document. New BVAM documents are not active until they are referenced in a counterparty issuance transaction.

Get all information for an asset

curl -X GET \
    https://bvam.tokenly.com/api/v1/asset/SOUP



> The above command returns data structured like this:

```json
{
  "asset": "SOUP",
  "filename": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json",
  "hash": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ",
  "uri": "https://bvam.tokenly.com/T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json",
  "txid": "4a06b9889f7553983cd2d4edc196ec9bc9abd52b955885238932c3d718952ead",
  "lastUpdated": "2016-09-10T15:43:18+0000",
  "assetInfo": {
    "locked": false,
    "description": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ",
    "divisible": true,
    "asset": "SOUP",
    "owner": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
    "issuer": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
    "supply": 10000000000000,
    "status": "valid",
    "tx_hash": "4a06b9889f7553983cd2d4edc196ec9bc9abd52b955885238932c3d718952ead",
    "block_index": 428929
  },
  "metadata": {
    "asset": "SOUP",
    "name": "Devon's Soup",
    "short_name": "Soup",
    "description": "All soup, all the time",
    "website": "https://devonweller.com",
    "meta": {
      "bvam_version": "1.0.0",
      "generated_by": "Devon"
    }
  },
  "bvamString": "{\n    \"asset\": \"SOUP\",\n    \"name\": \"Devon's Soup\",\n    \"short_name\": \"Soup\",\n    \"description\": \"All soup, all the time\",\n    \"website\": \"https://devonweller.com\",\n    \"meta\": {\n        \"bvam_version\": \"1.0.0\",\n        \"generated_by\": \"Devon\"\n    }\n}\n",
  "validated": true
}```

> Here is an example with enhanced asset information

```json
{
  "asset": "DEVON",
  "filename": null,
  "hash": null,
  "uri": null,
  "txid": null,
  "lastUpdated": null,
  "assetInfo": {
    "locked": false,
    "description": "tokens.devonweller.com/DEVON.json",
    "divisible": true,
    "asset": "DEVON",
    "owner": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
    "issuer": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
    "supply": 100000000,
    "status": "valid",
    "tx_hash": "2abe5ead8ca17d57ab6857faa24b257371af7da2e74b5e7f8d525b307a09a984",
    "block_index": 312851
  },
  "metadata": {
    "asset": "DEVON",
    "name": "DEVON",
    "description": "There can only be one.",
    "meta": {
      "bvam_version": "1.0.0"
    },
    "website": "http://www.devonweller.com",
    "images": [
      {
        "data": "data:image/png;base64,iVBORw0KGgoAA...",
        "size": "48x48"
      }
    ]
  },
  "bvamString": null,
  "validated": false
}

Returns all asset information. The assetInfo object includes data from the counterparty network. If there is validated BVAM data, it is returned in the metadata object. If BVAM data does not exist, then the metadata includes the enhanced asset info if it exists formatted as BVAM data. If there is no enhanced asset info, then the basic asset info formatted as BVAM data is returned in the metada object.

HTTP Request

GET https://bvam.tokenly.com/api/v1/asset/SOUP

Get multiple asset information

curl -X GET \
    https://bvam.tokenly.com/api/v1/assets?assets=SOUP,TOKENLY



> The above command returns data structured like this:

```json
[
    {
        "asset": "SOUP",
        "filename": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json",
        "hash": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ",
        "uri": "https://bvam.tokenly.com/T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json",
        "txid": "4a06b9889f7553983cd2d4edc196ec9bc9abd52b955885238932c3d718952ead",
        "lastUpdated": "2016-09-13T19:47:16+0000",
        "assetInfo": {
            "issuer": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
            "supply": 10000000000000,
            "locked": false,
            "owner": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
            "asset": "SOUP",
            "description": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ",
            "divisible": true,
            "status": "valid",
            "tx_hash": "4a06b9889f7553983cd2d4edc196ec9bc9abd52b955885238932c3d718952ead",
            "block_index": 428929
        },
        "metadata": {
            "asset": "SOUP",
            "name": "Devon's Soup",
            "short_name": "Soup",
            "description": "All soup, all the time",
            "website": "https://devonweller.com",
            "meta": {
                "bvam_version": "1.0.0",
                "generated_by": "Devon"
            }
        },
        "bvamString": "{\n    \"asset\": \"SOUP\",\n    \"name\": \"Devon's Soup\",\n    \"short_name\": \"Soup\",\n    \"description\": \"All soup, all the time\",\n    \"website\": \"https://devonweller.com\",\n    \"meta\": {\n        \"bvam_version\": \"1.0.0\",\n        \"generated_by\": \"Devon\"\n    }\n}\n",
        "validated": true
    },
    {
        "asset": "TOKENLY",
        "filename": null,
        "hash": null,
        "uri": null,
        "txid": null,
        "lastUpdated": null,
        "assetInfo": {
            "description": "Tokenly.co",
            "issuer": "12717MBviQxttaBVhFGRP1LxD8X6CaW452",
            "owner": "12717MBviQxttaBVhFGRP1LxD8X6CaW452",
            "supply": 10000000000000,
            "divisible": true,
            "asset": "TOKENLY",
            "locked": false,
            "status": "valid",
            "tx_hash": "a1d34271d7ebc983d37d351759e8a195605db2a9e8bef3ad50320005807e1062",
            "block_index": 310637
        },
        "metadata": {
            "asset": "TOKENLY",
            "name": "TOKENLY",
            "description": "Tokenly.co",
            "meta": {
                "bvam_version": "1.0.0"
            }
        },
        "bvamString": null,
        "validated": false
    }
]

Here is an example with enhanced asset information

{
  "asset": "DEVON",
  "filename": null,
  "hash": null,
  "uri": null,
  "txid": null,
  "lastUpdated": null,
  "assetInfo": {
    "locked": false,
    "description": "tokens.devonweller.com/DEVON.json",
    "divisible": true,
    "asset": "DEVON",
    "owner": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
    "issuer": "1AuTJDwH6xNqxRLEjPB7m86dgmerYVQ5G1",
    "supply": 100000000,
    "status": "valid",
    "tx_hash": "2abe5ead8ca17d57ab6857faa24b257371af7da2e74b5e7f8d525b307a09a984",
    "block_index": 312851
  },
  "metadata": {
    "asset": "DEVON",
    "name": "DEVON",
    "description": "There can only be one.",
    "meta": {
      "bvam_version": "1.0.0"
    },
    "website": "http://www.devonweller.com",
    "images": [
      {
        "data": "data:image/png;base64,iVBORw0KGgoAA...",
        "size": "48x48"
      }
    ]
  },
  "bvamString": null,
  "validated": false
}

Returns an array of information for multiple assets. See Get all information for an asset for details about the asset information type.

HTTP Request

https://bvam.tokenly.com/api/v1/assets

Query Parameters

Parameter Description
assets A comma separated list of asset names

List all active BVAM documents

curl -X GET \
    https://bvam.tokenly.com/api/v1/bvam/all



> The above command returns data structured like this:

```json
{
  "count": 1,
  "items": [
    {
      "filename": "T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json",
      "uri": "https://bvam.tokenly.com/T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json",
      "asset": "SOUP",
      "txid": "4a06b9889f7553983cd2d4edc196ec9bc9abd52b955885238932c3d718952ead",
      "lastUpdated": "2016-09-10T15:43:18+0000"
    }
  ]
}

Returns a list of all validated BVAM files.

HTTP Request

GET https://bvam.tokenly.com/api/v1/bvam/all

Add a New BVAM Document

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"bvam": {"asset": "MYTOKEN", "name": "My Token", "meta": {"bvam_version": "1.0.0"}}}' \
    https://bvam.tokenly.com/api/v1/bvam

The above command returns data structured like this:

{
  "uri": "http://bvam-provider.dev/T2XRkYJQz7xjUt6HeDoFxTLSMywak.json",
  "filename": "T2XRkYJQz7xjUt6HeDoFxTLSMywak.json",
  "asset": "MYTOKEN",
  "updatedAt": "2016-09-02T11:52:19+0000"
}

Validates the BVAM data, adds it to the database and calculates the BVAM hash.

HTTP Request

POST https://bvam.tokenly.com/api/v1/bvam

Body Parameters

Parameter Description
bvam A structured BVAM data object. This field can also be a JSON formatted string.

BVAM Category API Methods

Adds and validates a temporary BVAM Category document. New BVAM Category documents are not active until they are referenced in a counterparty broadcast transaction.

Add a New BVAM Category Schema

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"category":{"category_id":"Acme Rewards Program 201609a","properties":{"program_name":{"label":"Program Name","maxLength":127,"type":"string"}},"title":"Acme Rewards Program","version":"1.0.0"}}' \
    https://bvam.tokenly.com/api/v1/category

The above command returns data structured like this:

{
    "uri": "http://bvam-provider.dev/S3m1rrzBemasRcti5vAvrFW3yL9Fa.json",
    "filename": "S3m1rrzBemasRcti5vAvrFW3yL9Fa.json",
    "categoryId": "Acme Rewards Program 201609a",
    "title": "Acme Rewards Program",
    "version": "1.0.0",
    "updatedAt": "2016-09-02T15:57:32+0000"
}

Validates the BVAM Category Schema, adds it to the database and calculates the BVAM hash.

HTTP Request

POST https://bvam.tokenly.com/api/v1/category

Body Parameters

Parameter Description
category A structured BVAM Category Schema data object. This field can also be a JSON formatted string.

List all active BVAM Category Schemas

curl -X GET \
    https://bvam.tokenly.com/api/v1/category/all



> The above command returns data structured like this:

```json
{
    "count": 1,
    "items": [
        {
            "categoryId": "DWCGDS",
            "filename": "S3GEQCrn48HG8vfKzA9GqueuQgSwA.json",
            "lastUpdated": "2016-09-13T17:34:16+0000",
            "title": "Canned Goods",
            "txid": "45d491e49ce6ef3debbd853f2639b50f4db7369450e6b42a4a802cc5a22f9990",
            "uri": "https://bvam.tokenly.com/S3GEQCrn48HG8vfKzA9GqueuQgSwA.json",
            "version": "1.0.0"
        }
    ]
}

Returns a list of all validated BVAM categories.

HTTP Request

GET https://bvam.tokenly.com/api/v1/category/all

Public Resources

Returns BVAM and Category resources as JSON-formatted data.

Get a BVAM resource

curl -X GET \
    https://bvam.tokenly.com/T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json



> The above command returns data structured like this:

```json
{
  "asset": "SOUP",
  "name": "Devon's Soup",
  "short_name": "Soup",
  "description": "All soup, all the time",
  "website": "https://devonweller.com",
  "meta": {
    "bvam_version": "1.0.0",
    "generated_by": "Devon"
  }
}

Returns the exact BVAM JSON string. This string can be hashed to match the BVAM hash in the URL. BVAM JSON is backwards compatible with the enhanced asset info standard.

HTTP Request

GET https://bvam.tokenly.com/T2JAC8ix9g6PhsmKbeiXjtd2yEfCZ.json

Errors

The BVAM Provider API uses the following error codes:

Error Code Name Meaning
400 Bad Request The data contained a syntax error or was invalid
404 Not Found The resource is not found
405 Method Not Allowed You tried to access an endpoint with an invalid method
410 Gone The requested resource is no longer present
422 Unprocessable Entity The data was valid, but violated one or more validation rules
429 Too Many Requests Too Many Requests
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We’re temporarially offline for maintenance. Please try again later.