Transactions

List Transactions

List Transactions

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

Returns a list of transactions in the authorized scope

Headers

Name
Type
Description

authorization

string

bearer <JWT> 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

Parameter

Description

Default

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

Name
Type
Description

authorization

string

bearer <JWT> scoped to an Application, Organization or User

Request Body

Name
Type
Description

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

wallet_id

string

id of smart wallet funding transaction

value

string

value of transaction being created

{
    "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:

Metric

Description

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.

Signing

Behavior

Self-Custody

Managed

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

Parameter

Description

account_id

DEPRECATED id of the signing Account

data

unsigned transaction data to broadcast

key_id

network_id

params

signer

to

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

value

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:

Parameter

Description

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

Parameter

Description

data

signed or unsigned transaction data to broadcast

network_id

params

tx_provider

value

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:

Parameter

Description

priority

either normal (the default) or expedited documentation forthcoming

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

Name
Type
Description

id

string

id of target transaction

Headers

Name
Type
Description

authorization

string

bearer <JWT> 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

Parameter

Description

id

id of the Transaction

PreviousTokenizationNextWallets

Last updated