Transactions

List Transactions

List Transactions

GET https://nchain.provide.services/api/v1/transactions

Returns a list of transactions in the authorized scope

Headers

NameTypeDescription

authorization

string

bearer scoped to an

Application

,

Organization

or

User

[
    {
        "id": "b0574ac4-ff6e-4385-be56-27f3eb2c87a6",
        "created_at": "2021-08-17T01:42:35.395958Z",
        "network_id": "07102258-5e49-480e-86af-6d0c3260827d",
        "user_id": "49a02f33-33f2-4d69-a301-ffb1933e77cc",
        "wallet_id": "a20a4b36-4793-43c2-bcf3-077e9c73bc8f",
        "hd_derivation_path": "m/44'/60'/0'/0/0",
        "to": "7c8fe6f1-38c3-4da1-b4b7-7591c6d0ca7c",
        "value": 0,
        "data": null,
        "hash": "0xeec89fa14f1326a00e1cb1d0979d1d66b63091de18a3309d32aa62286bcc84ef",
        "status": "pending",
        "ref": null,
        "description": null,
        "block": null
    },
    {
        "id": "203fda12-7c78-4e50-9ecb-7fe6b64b9c9f",
        "created_at": "2021-08-17T01:42:33.827658Z",
        "network_id": "07102258-5e49-480e-86af-6d0c3260827d",
        "user_id": "49a02f33-33f2-4d69-a301-ffb1933e77cc",
        "wallet_id": "a20a4b36-4793-43c2-bcf3-077e9c73bc8f",
        "hd_derivation_path": "m/44'/60'/0'/0/0",
        "to": "7c8fe6f1-38c3-4da1-b4b7-7591c6d0ca7c",
        "value": 0,
        "data": null,
        "hash": "0x5660e3aa927cf3b96538c62b220d3684e6d7fba187e56f12a209dde21beec787",
        "status": "pending",
        "ref": null,
        "description": null,
        "block": null
    },
]
curl -i \
     -H 'authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
     https://nchain.provide.services/api/v1/transactions
HTTP/2 200
date: Sun, 10 Jun 2019 03:50:04 GMT
content-type: application/json; charset=UTF-8
access-control-allow-credentials: true
access-control-allow-headers: Accept, Accept-Encoding, Authorization, Cache-Control, Content-Length, Content-Type, Origin, User-Agent, X-CSRF-Token, X-Requested-With
access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
access-control-allow-origin: *
access-control-expose-headers: X-Total-Results-Count
x-total-results-count: 3

Retrieve a list of transactions scoped to the authorized User or Application.

Query Parameters

ParameterDescriptionDefault

filter_contract_creations

when true, contract creation transactions are filtered

false

status

comma-delimited list of statuses by which the transactions response is filtered

n/a

network_id

id of the Network where the transaction was broadcast

n/a

account_id

id of the Account which signed the transaction

n/a

from

network address of the sender of the transaction (corresponds to the Account address)

n/a

to

network address of the recipient of the transaction

n/a

Create & Broadcast Transaction

Create and broadcast a transaction in a chain- and protocol-agnostic manner.

Create Transaction

POST https://nchain.provide.services/api/v1/transactions

Creates and broadcasts a transaction in a chain- and protocol-agnostic manner

Headers

NameTypeDescription

authorization

string

bearer scoped to an

Application

,

Organization

or

\

User

Request Body

NameTypeDescription

hd_derivation_path

string

type of derivation path

network_id

string

id of network on which to broadcast transaction

to

string

destination address of transaction

user_id

string

id of user associated with transaction

value

string

value of transaction being created

wallet_id

string

id of smart wallet funding transaction

{
    "id": "b0574ac4-ff6e-4385-be56-27f3eb2c87a6",
    "created_at": "2021-08-17T01:42:35.395957622Z",
    "network_id": "07102258-5e49-480e-86af-6d0c3260827d",
    "user_id": "49a02f33-33f2-4d69-a301-ffb1933e77cc",
    "wallet_id": "a20a4b36-4793-43c2-bcf3-077e9c73bc8f",
    "hd_derivation_path": "m/44'/60'/0'/0/0",
    "to": "7c8fe6f1-38c3-4da1-b4b7-7591c6d0ca7c",
    "value": 0,
    "data": null,
    "hash": "0xeec89fa14f1326a00e1cb1d0979d1d66b63091de18a3309d32aa62286bcc84ef",
    "status": "pending",
    "ref": null,
    "description": null,
    "block": null,
    "broadcast_at": "2021-08-17T01:42:35.537426527Z"
}
curl -i \
     -H 'authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
     -H 'content-type: application/json' \
     https://nchain.provide.services/api/v1/transactions \
     -d '{"account_id": "network_id": "ef976635-545b-46c6-9576-4e3a893a68e9", "key_id": "e6ef498b-589e-4514-9924-278b7bd6e3de", "to": "0xc04B5fc7c8D7d63d1b1c24dfA92a59e74859055C", "value": 0}'
HTTP/2 201

This API provides an asynchronous, fault-tolerant mechanism for providing some guarantees about how a well-formed transaction will become eventually-consistent with the underlying target Network. Currently, transactions are guaranteed to be successfully broadcast to the target network or timeout within 5 minutes. If a transaction is unable to be broadcast to the network for any reason (i.e., network reachability, invalid nonce etc.) it is retried every 60 seconds. It is likely these retry and timeout constraints will be made more configurable in a future release.

In addition to the asynchronous and resilient nature of broadcasting transactions using this API, instrumentation of the full transaction lifecycle is captured for each transaction. This currently includes the following metrics:

MetricDescription

broadcast_at

timestamp indicating when the transaction was broadcast to the network

finalized_at

timestamp indicating when the transaction was included in a block

published_at

timestamp indicating when the transaction was published for async processing

queue_latency

amount of time, in milliseconds, the transaction was queued for async processing

network_latency

amount of time, in milliseconds, the transaction was pending inclusion in a block

e2e_latency

amount of time, in milliseconds, of the full transaction lifecycle

The following request illustrates how to create a new Transaction for broadcast to an Ethereum-based blockchain:

A few modes of operation exist in the context of a request to the create/broadcast transaction API, specifically related to how signing is handled. A transaction is considered to be either self-custody or managed and each mode supports pre-signed transactions.

SigningBehavior

Self-Custody

the API assumes you are running Provide infrastructure and are either (i) in custody of your own private keys and using them within NChain directly to sign transactions, (ii) using the API as a fault-tolerant gateway to broadcast pre-signed transactions or (iii) configuring NChain to delegate the signing of transactions to the Vault service

Managed

the API will forward your transaction to the Managed Transactions API for broadcast

The parameters provided to the API in each create/broadcast transaction request determine how the API handles the signing and attempted broadcast of the transaction (i.e., whether the transaction is self-custody or managed).

Self-Custody Request Parameters

ParameterDescription

account_id

DEPRECATED id of the signing Account

data

unsigned transaction data to broadcast

key_id

id of the Vault Key which will be used to sign the Transaction; required in the absence of a signer

network_id

id of the Network on which the Transaction will be broadcast

params

arbitrary optional parameters provided for constructing and broadcasting a valid Transaction for the target Network; useful for setting gas, gas_price and subsidize, for example, in the case of an EVM-based Transaction

signer

public network address associated with the private key which signed the given data, provided data is signed externally; if unsigned data is provided, the given signer is assumed to represent an Account or Wallet that can be resolved to a Vault Key, which is then used to sign the given data

to

public network address of the recipient of the Transaction, if applicable

value

total amount of value, represented in the smallest standard denomination of native currency for the target Network (i.e., wei), to be transferred by the sender to the recipient

Including both a key_id and signer as part of a create/broadcast request will result in a 400 Bad Request.

Optional Parameters

The following are supported as optional params of a self-custody create/broadcast transaction request:

ParameterDescription

gas

maximum gas to be spent on the Transaction

gas_price

price per unit of gas, specified in units customary to the target Network

nonce

nonce to be used for the Transaction

If gas is not provided, it will be estimated for the contemplated transaction execution and set automatically. This will be sufficient for most transactions, but including gas with your request is considered a best-practice. If gas_price is not provided, an appropriate Gas Price Oracle will be used to calculate the gas price to be offered to the network. If a nonce is not provided, the next nonce for the signing account is resolved automatically using the blockchain and mempool, which will be sufficient for most transactions.

Managed Request Parameters

ParameterDescription

data

signed or unsigned transaction data to broadcast

network_id

id of the Network on which the Transaction will be broadcast

params

arbitrary optional parameters to enable faster finality or indicate a subsidy should be used

tx_provider

supported Managed Transactions provider

value

total amount of value, represented in the smallest standard denomination of native currency for the target Network (i.e., wei), to be transferred by the sender to the recipient

The tx_provider parameter causes the API to attempt to broadcast the new transaction using the Managed Transaction API. If the given tx_provider is valid and your account is eligible to use the service, value + gas are paid on your behalf and billed in arrears.

Optional Parameters

The following are supported as optional params of a managed create/broadcast transaction request:

ParameterDescription

priority

either normal (the default) or expedited documentation forthcoming

subsidize

public network address or id of the Vault Key to subsidize

The subsidize parameter is highly experimental at this time. Additional documentation about how to use this feature of the Managed Transactions API will be included here when it becomes available.

⚠️Documentation for broadcasting pre-signed transactions will be included here in the near future.

Managed Transactions API

Provide Payments has developed a Managed Transactions API, to facilitate enterprise adoption of public blockchain applications and protocols via traditional enterprise procurement processes (i.e., no cryptocurrency or tokens ever need to be acquired by users). Support for paying network transaction fees (i.e., gas) has been enabled on an experimental basis when using the create/broadcast transaction API (see the tx_provider and optional subsidize).

Note that only certain Ethereum-based testnets are currently supported. A full list of supported networks and professional custody providers can be found here.

Retrieve Transaction Details

Get Transaction Details

GET https://nchain.provide.services/api/v1/transactions/:id

Retrieves detailed information about a specified transaction

Path Parameters

NameTypeDescription

id

string

id of target transaction

Headers

NameTypeDescription

authorization

string

bearer scoped to an

Application

,

Organization

or

User

[
    {
        "id": "327b202c-7e13-41ac-ba1f-14dc75b0f169",
        "created_at": "2021-08-16T18:56:24.285528Z",
        "network_id": "07102258-5e49-480e-86af-6d0c3260827d",
        "application_id": "8675134a-32d7-40dc-9698-0457800b58db",
        "account_id": "9a24779c-d9b0-43aa-a34f-77d8df044109",
        "to": "0x",
        "value": 0,
        "data": "0x",
        "hash": "0x43f032babe3a63e5bc25c0c7bd087a16368ad1d1c9cad5ebdb219001d8fd5919",
        "status": "success",
        "ref": "911014d1-125c-468e-8d20-a2cc87bdcc0f",
        "description": null,
        "block": 9126635,
        "block_timestamp": "2021-08-16T18:56:28Z",
        "finalized_at": "2021-08-16T18:56:28.545678Z"
    }
]
curl -i \
     -H 'authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
     https://nchain.provide.services/api/v1/transactions/6e401894-f091-4481-b978-e2a45eca0fd1
HTTP/2 200
date: Sun, 10 Jun 2019 04:52:30 GMT
content-type: application/json; charset=UTF-8
access-control-allow-credentials: true
access-control-allow-headers: Accept, Accept-Encoding, Authorization, Cache-Control, Content-Length, Content-Type, Origin, User-Agent, X-CSRF-Token, X-Requested-With
access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
access-control-allow-origin: *
access-control-expose-headers: X-Total-Results-Count

Fetch details about a specific transaction. When available, this API returns VM tracing details.

URL Parameters

ParameterDescription

id

id of the Transaction

PreviousTokenizationNextWallets

Last updated