api

Getting Started

To start making calls to the Onename API, you'll need API credentials (an App ID and an App secret key).

Sign Up for an API Account

Lookup users

Looks up the data for one or more users by their usernames. In order to perform more than one lookup at once, include a set of comma-separated usernames in the URL in place of the single username.

parameters
-

returns

Returns an object with a top-level key for each username looked up. Each top-level key contains an sub-object that has a "profile" field and a "verifications" field.

Try it out

Definition

GET https://api.onename.com/v1/users/{usernames}

Example Request

curl https://api.onename.com/v1/users/fredwilson \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "fredwilson": {
    "profile": {
      "avatar": {
        "url": "https://s3.amazonaws.com/kd4/fredwilson1"
      },
      "bio": "I am a VC",
      "bitcoin": {
        "address": "1Fbi3WDPEK6FxKppCXReCPFTgr9KhWhNB7"
      },
      "cover": {
        "url": "https://s3.amazonaws.com/dx3/fredwilson"
      },
      "facebook": {
        "proof": {
          "url": "https://facebook.com/fred.wilson.963871/posts/10100401430876108"
        },
        "username": "fred.wilson.963871"
      },
      "graph": {
        "url": "https://s3.amazonaws.com/grph/fredwilson"
      },
      "location": {
        "formatted": "New York City"
      },
      "name": {
        "formatted": "Fred Wilson"
      },
      "twitter": {
        "proof": {
          "url": "https://twitter.com/fredwilson/status/533040726146162689"
        },
        "username": "fredwilson"
      },
      "v": "0.2",
      "website": "http://avc.com"
    },
    "verifications": [
      {
        "identifier": "fredwilson",
        "proof_url": "https://twitter.com/fredwilson/status/533040726146162689",
        "service": "twitter",
        "valid": true
      },
      {
        "identifier": "fred.wilson.963871",
        "proof_url": "https://facebook.com/fred.wilson.963871/posts/10100401430876108",
        "service": "facebook",
        "valid": true
      }
    ]
  }
}

Search users

Takes in a search query and returns a list of results that match the search. The query is matched against +usernames, full names, and twitter handles by default. It's also possible to explicitly search verified Twitter, Facebook, Github accounts, and verified domains. This can be done by using search queries like twitter:albertwenger, facebook:g3lepage, github:shea256, domain:muneebali.com

parameters
query
The text to search for.

returns

Returns an array of results, where each result has a \"profile\" object.

Try it out

Definition

GET https://api.onename.com/v1/search

Example Request

curl https://api.onename.com/v1/search?query=wenger \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "results": [
    {
      "profile": {
        "avatar": {
          "url": "https://pbs.twimg.com/profile_images/1773890030/aew_artistic_bigger.gif"
        },
        "bio": "VC at USV.com",
        "bitcoin": {
          "address": "1QHDGGLEKK7FZWsBEL78acV9edGCTarqXt"
        },
        "cover": {
          "url": "https://s3.amazonaws.com/dx3/albertwenger"
        },
        "facebook": {
          "proof": {
            "url": "https://www.facebook.com/albertwenger/posts/10152554952070219"
          },
          "username": "albertwenger"
        },
        "github": {
          "proof": {
            "url": "https://gist.github.com/albertwenger/03c1b5db3880998115fa"
          },
          "username": "albertwenger"
        },
        "graph": {
          "url": "https://s3.amazonaws.com/grph/albertwenger"
        },
        "location": {
          "formatted": "New York"
        },
        "name": {
          "formatted": "Albert Wenger"
        },
        "twitter": {
          "proof": {
            "url": "https://twitter.com/albertwenger/status/499594071401197568"
          },
          "username": "albertwenger"
        },
        "v": "0.2",
        "website": "http://continuations.com"
      },
      "username": "albertwenger"
    }
  ]
}

Register users

parameters
username
The username (blockchain ID username) that is to be registered.
recipient_address
The bitcoin address that the blockchain ID will be transferred to once it has been registered.
profile (optional)
The data to be associated with the blockchain ID.

returns

Returns an object with a status that is either "success" or "error".

Definition

POST https://api.onename.com/v1/users

Example Request

curl https://api.onename.com/v1/users \
    -u 'YOUR-API-ID:YOUR-API-SECRET' \
    -d '{"username": "fredwilson",
         "recipient_address": "152f1muMCNa7goXYhYAQC61hxEgGacmncB",
         "profile": {"bio": "I am a VC"}}' \
    -H 'Content-type: application/json' \
    -X POST

Example Response

{
    "status": "success"
}

Update users

parameters
profile
JSON profile data that should be associated with the username.
owner_pubkey
Public key of the bitcoin address that owns the username.

returns

Returns an object with an unsigned transaction "unsigned_tx" in hex format.

Definition

POST https://api.onename.com/v1/users/{username}/update

Example Request

curl https://api.onename.com/v1/users/fredwilson/update \
    -u 'YOUR-API-ID:YOUR-API-SECRET' \
    -d '{"profile": {"bio": "I am a VC"}, 
         "owner_pubkey": "02b262e2bdb4fee2834115aab77..."}' \
    -H 'Content-type: application/json' \
    -X POST

Example Response

{
    "unsigned_tx": "01000000027757f96d886019cf8307e3b3c35bee845...."
}

Transfer users

parameters
transfer_address
Bitcoin address of the new owner address.
owner_pubkey
Public key of the bitcoin address that currently owns the username.

returns

Returns an object with an unsigned transaction "unsigned_tx" in hex format.

Definition

POST https://api.onename.com/v1/users/{username}/transfer

Example Request

curl https://api.onename.com/v1/users/fredwilson/transfer \
    -u 'YOUR-API-ID:YOUR-API-SECRET' \
    -d '{"transfer_address": "19bXfGsGEXewR6TyAV3b89cSHBtFFewXt6", 
         "owner_pubkey": "02b262e2bdb4fee2834115aab77..."}' \
    -H 'Content-type: application/json' \
    -X POST

Example Response

{
    "unsigned_tx": "01000000027757f96d886019cf8307e3b3c35bee845...."
}

Get all users

Gets all data for the decentralized namespace, including the total number of users registered.

parameters
-

returns

Returns an object with "stats", and "usernames". "stats" is a sub-object which in turn contains a "registrations" field that reflects a running count of the total users registered. "usernames" is a list of all usernames in the namespace.

Try it out

Definition

GET https://api.onename.com/v1/users

Example Request

curl https://api.onename.com/v1/users \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "stats": {
    "registrations": "37000"
  },
  "usernames": [
    "fredwilson",
    ...
  ]
}

Broadcast transactions

Takes in a signed transaction (in hex format) and broadcasts it to the network. If the transaction is successfully broadcasted, the transaction hash is returned in the response.

parameters
signed_hex
A signed transaction in hex format.

returns

Returns an object with a status that is either "success" or "error".

Definition

POST https://api.onename.com/v1/transactions

Example Request

curl https://api.onename.com/v1/transactions \
    -u 'YOUR-API-ID:YOUR-API-SECRET' \
    -d '{"signed_hex": "00710000015e98119922f0b"}' \
    -H 'Content-Type: application/json' \
    -X POST

Example Response

{
    "status": "success"
}

Get unspent outputs

Retrieves the unspent outputs for a given address so they can be used for building transactions.

parameters
-

returns

Returns an array of unspent outputs for a provided address.

Try it out

Definition

GET https://api.onename.com/v1/addresses/{address}/unspents

Example Request

curl https://api.onename.com/v1/addresses/19bXfGsGEXewR6TyAV3b89cSHBtFFewXt6/unspents \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "unspents": [
    {
      "confirmations": 6715, 
      "output_index": 1, 
      "script_hex": "76a9145e48be183fbb5c3990e29aedd3b44367c28a5e4388ac", 
      "transaction_hash": "97a2dc2270be32f322c4e9fdf4de9754136a0c9a83abe0d655a6edc19cf01e15", 
      "value": 5500
    }, 
    {
      "confirmations": 7523, 
      "output_index": 1, 
      "script_hex": "76a9145e48be183fbb5c3990e29aedd3b44367c28a5e4388ac", 
      "transaction_hash": "d4d5a583a229409af3c9c29e8f9cb5b40b8c655509307ad0396a0d38fd7df906", 
      "value": 5500
    }
  ]
}

Get names owned

Retrieves a list of names owned by the address provided.

parameters
-

returns

Returns an array of the names that the address owns.

Try it out

Definition

GET https://api.onename.com/v1/addresses/{address}/names

Example Request

curl https://api.onename.com/v1/addresses/1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP/names \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "names": [
    "muneeb.id"
  ]
}

Get DKIM public key

Retrieves a DKIM public key for given domain, using the "blockchainid._domainkey" subdomain DNS record.

parameters
-

returns

Returns a DKIM public key.

Try it out

Definition

GET https://api.onename.com/v1/domains/{domain}/dkim

Example Request

curl https://api.onename.com/v1/domains/onename.com/dkim \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "key_curve": "secp256k1", 
  "key_type": "ecdsa", 
  "public_key": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE3s0qMljBNrC6mmfMLQp1B+v8haqeOswDV4r0p6HogXA7JT0bOt4nIom6IQeE+TQRzdn4fz+VWBxIBkL9nAXIRQ=="
}

Get user stats

Gets all user stats.

parameters
-

returns

Returns an object with "stats".

Try it out

Definition

GET https://api.onename.com/v1/stats/users

Example Request

curl https://api.onename.com/v1/stats/users \
    -u 'YOUR-API-ID:YOUR-API-SECRET'

Example Response

{
  "stats": {
    "registrations": "31804"
  }
}