Public (non-signed) interfaces

GET /api/v1/version/

Mandatory Inputs

Mandatory Outputs

Example:

GET /api/v1/wallet

Mandatory Inputs

Mandatory Outputs

Example:

GET api/v1/wallet/:address

Mandatory Inputs

Mandatory Outputs

Example:

POST /api/v1/wallet

This is a shortcut interface - the same operation can be done through /api/v1/wallets/ but this interface is more obviously named for the operation itself.  This creates a wallet and submits it to the network.  A new wallet can be used immediately in the current coinbase, but requires settlement time for the entire network.

Mandatory Inputs

Mandatory Outputs

POST /api/v1/vend

This interface takes an item owned by the current user, and puts it up for sale.

Mandatory Inputs

Mandatory Outputs

GET /api/v1/vend

This interface lists the currently available items to buy - the item list is capped at 200 items from the currently available listing..

Mandatory Inputs

Mandatory Outputs

GET /api/v1/vend/:txid

This interface returns the requested sale item information.

Mandatory Inputs

Mandatory Outputs

GET /api/v1/vend/geo/:lat/:lon/:dist

This interface returns items available from the given :dist value (in KM) from the given coordinates.  Matches are limited to 200.

Mandatory Inputs

Mandatory Outputs

GET /api/v1/item

This interface lists the current items - the item list is capped at 200 items from the currently available listing, and is really only useful for debugging on a local image.

Mandatory Inputs

Mandatory Outputs

GET /api/v1/items/:id

This interface returns the given item record as is currently seen in the coinbase.

Mandatory Inputs

Mandatory Outputs

GET /api/v1/items/venue/:venue

This interface returns the given item records from this venue ID.

Mandatory Inputs

Mandatory Outputs

GET /api/v1/items/geo/:lat/:lon/:dist

This interface returns the given item records from geographical location.

Mandatory Inputs

Mandatory Outputs

POST /api/v1/items/

This interface adds a given transaction into the work queue.

Mandatory Inputs

The cp is a complicated protocol with a very simply interface.  cp is a fully integrated stack with a basic, completely open source implementation of the protocol.  The cp is an integrated blockchain created to track, move, and manage digital items.  The blockchain is designed to hold the items directly (up to 2MB).

All items belong to a given address, which belongs to anyone who knows the needed private key for it.  Each address is the hash of a ECDSA key and is 24-32 characters.

All inputs and returns are in standard JSON data format.  The return packet always contains the tag ‘result’ that hold the result of the operation.  The string “ok” signifies no errors that would affect getting a result.  The optional string “warnings” contains clear English text in regards to the operations - it may contains text to the effect that the server is overloaded, or this session is reaching its query limit.

Possible values for “result” include:

Value for ‘result’

Meaning

abend-invalid-signature

Packet was invalid - possible additional information in “warnings”

abend-flare

This IP address has been flagged as a possible DOS attack because of repeated bad or trivial connections.  Further connections will be ignored and may be forcibly trapped at the OS layer

abend-no-api-entry

Requested operation is not valid

abend-missing-mandatory-fields

Packet is missing one or more fields that are needed - additional information may exist in “warning” but this is not mandatory.

abend-dust-transaction

Packet has been identified as a ‘dust’ transaction - which is a possible DOS vector - and has been rejected by the node.  The value of the transaction and its fees are trivial and appear to be network spam.  These values are implementation specific.

abend-invalid-to

Transaction is attempting to move an item to a non-existent or revoked address

abend-invalid-from

Transaction is attempting to move items from a non-existent address

abend-unknown-transaction

Transaction type is one that is not recognized by this node.

abend-too-large

Packet exceeds the current network maximum

abend-max-calls-exceeded

The number of queries for this node type has been exceeded.  Try again later (this is to restrict calls from Internet nodes in favor of local ones for data processing)

abend-malformed-address

wallet address does not match the correct format

abend-unknown-transaction

item is not a known type

abend-already-vending

item is already for sale - cannot relist

abend-low-balance

source wallet cannot cover this transaction

abend-necrotic-transaction

transaction is referring to an expired or otherwise worthless item

abend-not-implemented

optional interface not implemented

abend-pending

unable to complete since previously submitted transactions for same item have not completed

Public (non-signed) interfaces

GET /api/v1/version/

Mandatory Inputs

None - input data will be silently discarded.

Mandatory Outputs

Tag

Meaning

result

required operation result

vendor

text string describing the distributor of this node

version

object containing at least the tags “core” and “hard_fork”, which describes the version of the software and the protocol version, respectively.  the version described in this document is hard_fork 1.

Example:

{"result":"ok","vendor":"census foundation baseline implementation","version":{"core":"0.01","hard_fork":1}}

GET /api/v1/wallet

Mandatory Inputs

None

Mandatory Outputs

Tag

Meaning

result

required operation result

vendor

text string describing the distributor of this node

version

object containing at least the tags “core” and “hard_fork”, which describes the version of the software and the protocol version, respectively.  the version described in this document is hard_fork 1.

Example:

{"result":"ok","vendor":"census foundation baseline implementation","version":{"core":"0.01","hard_fork":1}}

GET api/v1/wallet/:address

Mandatory Inputs

address is the wallet address to look up

Mandatory Outputs

Tag

Meaning

result

required operation result

vendor

text string describing the distributor of this node

version

object containing at least the tags “core” and “hard_fork”, which describes the version of the software and the protocol version, respectively.  the version described in this document is hard_fork 1.

Example:

{"result":"ok","vendor":"census foundation baseline implementation","version":{"core":"0.01","hard_fork":1}}

POST /api/v1/wallet

This is a shortcut interface - the same operation can be done through /api/v1/wallets/ but this interface is more obviously named for the operation itself.  This creates a wallet and submits it to the network.  A new wallet can be used immediately in the current coinbase, but requires settlement time for the entire network.

Mandatory Inputs

Tag

Meaning

POST data

item to verify and add

Mandatory Outputs

Tag

Meaning

result

required operation result

POST /api/v1/vend

This interface takes an item owned by the current user, and puts it up for sale.

Mandatory Inputs

Tag

Meaning

POST data

item to sell

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/vend

This interface lists the currently available items to buy - the item list is capped at 200 items from the currently available listing..

Mandatory Inputs

Tag

Meaning

None

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/vend/:txid

This interface returns the requested sale item information.

Mandatory Inputs

Tag

Meaning

:txid

ID of transaction

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/vend/geo/:lat/:lon/:dist

This interface returns items available from the given :dist value (in KM) from the given coordinates.  Matches are limited to 200.

Mandatory Inputs

Tag

Meaning

:lat

Latitude  (float)

:lon

Longitude (float)

:dist

Distance in km

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/item

This interface lists the current items - the item list is capped at 200 items from the currently available listing, and is really only useful for debugging on a local image.

Mandatory Inputs

Tag

Meaning

None

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/items/:id

This interface returns the given item record as is currently seen in the coinbase.

Mandatory Inputs

Tag

Meaning

:item

TXID of item to return

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/items/venue/:venue

This interface returns the given item records from this venue ID.

Mandatory Inputs

Tag

Meaning

:venue

ID of venue

Mandatory Outputs

Tag

Meaning

result

required operation result

GET /api/v1/items/geo/:lat/:lon/:dist

This interface returns the given item records from geographical location.

Mandatory Inputs

Tag

Meaning

:lat

Latitude

:lon

Longitude

:dist

Distance in km

Mandatory Outputs

Tag

Meaning

result

required operation result

POST /api/v1/buy/

This interface adds a buy transaction to the work queue.

Mandatory Inputs

Tag

Meaning

POST data

Valid JSON for server API level

Mandatory Outputs

Tag

Meaning

result

required operation result