Download OpenAPI specification:Download
Filecoin JSON REST API Description
The authentication scheme for this API is implementation dependent. Implementations should feel free to use the scheme and granularity they deem fit. This document describes the scheme used by the go-filecoin daemon.
Go-filecoin will initially (v0) support a simple all or nothing authentication and authorization suitable for use by the owner/operator of the current node, and nothing else. Consumers of this API must provide a bearer token included in the Authorization header of each request. This token is provided by the go-filecoin node for use by the caller via some out of band mechanism (like a file created on the filesystem upon initialization or upon startup). More sophisticated authentication and authorization will follow.
The nature of this style of authentication makes it suitable for use only when served over SSL/TLS.
Here is an example of using a node provided bearer token and a node provided CA cert used for self-signed TLS with curl. This example assumes the cert and token both reside in the .filecoin folder and where generated by the go-filecoin daemon:
$ AUTH="Authorization: Bearer $(xxd -ps -u -c 1000 $HOME/.filecoin/api/admin.token)"
$ curl -X GET --cacert $HOME/.filecoin/api/tls.cert --header "$AUTH" \
> https://localhost:3453/api/filecoin/v0/tipsets| Security scheme type: | HTTP |
|---|---|
| HTTP Authorization Scheme | Bearer Token |
List Tipsets currently known to this node in reverse height order
| nextPageToken | string Next page token |
Success
Access token is missing or invalid
Return information about the Tipset with the specified ID
| tipsetId required | string ID of the Tipset to fetch |
Success
Access token is missing or invalid
Return information about the Block with the specified ID
| blockId required | string ID of the Block to fetch |
Success
Access token is missing or invalid
This method sends a new Message to an Actor recipient.
| to | string |
| value | number |
| gasPrice | number |
| gasLimit | number |
| method | string |
| parameters | object |
Success
Access token is missing or invalid
Return information about the ExecutedMessage with the specified ID. An executed Message is one that has been included in a valid block in the chain. It includes return value and status information.
| executedMessageId required | string ID of the executed message to fetch |
Success
Access token is missing or invalid
List Actors currently known to this node in address order
| nextPageToken | string Next page token |
Success
Return information about the Actor with the specified Address
| address required | string The address of the Actor to fetch |
Success
This endpoint accepts a voucher from the PaymentChannel target and redeems it. Upon checking the validity and successfully checking the voucher's condition the specified funds will be transfered from the channel to the target.
| paymentChannelId required | string ID of the PaymentChannel to fetch |
| amount | number The amount of FIL this Voucher is worth. This amount is sent to the target when this voucher is redeemed. |
| validAt | number The block height on or after which this Voucher can be redeemed. |
| condition | object The condition that must evaluate to true for this Voucher to be redeemed. |
| signature | string The signature over all the data in this Voucher |
Success
This endpoint accepts voucher details and returns a new signed voucher suitable for off chain transmission to the PaymentChannel target for later redemption. Only the PaymentChannel payer (creator) can call this endpoint successfully.
| paymentChannelId required | string ID of the PaymentChannel to fetch |
| amount | number The amount of FIL this Voucher is worth. This amount is sent to the target when this voucher is redeemed. |
| validAt | number The block height on or after which this Voucher can be redeemed. |
| condition | object The condition that must evaluate to true for this Voucher to be redeemed. |
| signature | string The signature over all the data in this Voucher |
Success
List all PaymentChannels known to this node
| nextPageToken | string Next page token |
Success
This endpoint creates a new PaymentChannel with the specified characteristics
| targetActorId | string The address of the account to which funds will be transferred by this PaymentChannel upon successful redemption of vouchers |
| amount | number The total amount of FIL that is in this PaymentChannel and payable to the target |
| agreedEol | number The original chain height at which this PaymentChannel will expire. Specified upon creation and optionally extended by the creator of the channel. |
Success
Find a PaymentChannel by ID and return it
| paymentChannelId required | string ID of the PaymentChannel to fetch |
Success
This endpoint extends the duration of an existing PaymentChannel, increasing the block height at which the PaymentChannel will timeout. Only the payer (creator) or the PaymentChannel can successfully call this endpoint.
| paymentChannelId required | string ID of the PaymentChannel to fetch |
| agreedEol | number The new chain (increased) height at which this PaymentChannel will expire. |
Success
This endpoint reduces the actual eol (effective end date) of the PaymentChannel in an attempt to free up the funds in the channel for earlier reclaming. This endpoint can only successfullly be called by the PaymentChannel's payer as the cancel message needs to originate from that account. Cancel doesn't immediately close a channel but instead reduces the lifetime of the channel leaving a grace period during which the payee can undo the cancellation by submitting a valid voucher, thereby proving that the channel is still in use.
| paymentChannelId required | string ID of the Channel to cancel |
Success
This endpoint is used by the creator (payer) of a PaymentChannel to reclaim unspent funds when a PaymentChannel has timed out (the chain height has exceeded the eol of the PaymentChannel). It can only successfully be called by the PaymentChannel's payer on a timed out PaymentChannel.
| paymentChannelId required | string ID of the Channel to reclaim |
Success
Get information about the current Filecoin Node.
Success
This method imports data into the local node's temporary storage so that it can be transferred to a storage miner.
Success
Fetch piece data from the local node's temporary storage.
| pieceId required | string ID of the piece previously returned by corresponding createPiece POST method. |
If the request succeeds, the server returns the original data used to create the piece.
This endpoint returns all Asks known to the current node ordered lexically by the Ask ID
| minerId | string Example: minerId=t2ytzk7whxrjb77kg4wd5fqy2cfse5jxajkqczfcq Filter returned asks by minerId. Only Asks from this miner will be returned. |
| active | boolean Example: active=true Filter returned asks to include only those that are still active, meaning the current node's tipset height doesn't exceed that of the Ask's specified expiration. |
| nextPageToken | string Next page token |
Success
This method creates a new storage market ask and publishes it for storage buyers to find and act on.
| kind | string Value: "ask" |
| price | number The price in FIL per byte per blocktime being proposed in this Ask. |
| expiry | number The block height at which this Ask expires. |
Success
Fetch data about an Ask by the Ask ID.
| askId required | string ID of the Ask to fetch. |
If the request succeeds, the server returns the requested Ask.
This endpoint returns a list of all deals known to the current node.
| minerId | string Example: minerId=t2ytzk7whxrjb77kg4wd5fqy2cfse5jxajkqczfcq Filter returned Deals by minerId. Only Deals made with (or proposed to) the specified miner will be returned. |
| clientId | string Example: clientId=t17vmiuyzqa3ygd4gsj5rsgglbj737wyztb4cohfy Filter returned Deals by clientId. Only Deals initiated by the specified client will be returned. |
| pieceId | string Example: pieceId=QmYRHQCRVSznLwaR8kXtVH4KSZU5fqFPPSkxv9xsJV2QCY Filter returned Deals by pieceId. Only Deals made to store the specified pieceId will be returned. |
| nextPageToken | string Next page token |
Success
This endpoint initiates a storage deal with a storage miner. It will create an appropriate PaymentChannel and vouchers, and pass the deal to the target storage miner to await acceptance or rejection.
| minerActorId | string The ID of the storage miner that is fulfilling this StorageDeal |
| pieceId | string The ID of the Picee being stored |
| askId | string The ID of the Ask from the target miner for which this StorageDeal is to be proposed |
| duration | number The duration of this StorageDeal in blocks |
| status | string Enum: "unknown" "rejected" "accepted" "started" "failed" "staged" "sealing" "complete" The current status of the StorageDeal |
Success
Actor is the central abstraction of entities in the system.
See the Actor Specification and the Actor Definition for more information.
Both individual accounts, as well as contracts (user & system level) are represented as actors. An actor has the following core functionality implemented on a system level:
Balance fieldCode fieldNonce fieldValue sent to a non-existent address will be tracked as an empty actor that has a Balance but nil Code and Memory. You must nil check Code cids before comparing them.
More specific capabilities for individual accounts or contract specific must be implemented inside the code.
| kind | string Value: "actor" |
| address | string The identifier that refers to an Actor in the Filecoin state. All Actors have an address. To learn more, take a look at the address spec.. |
| role | string Enum: "Init" "Account" "StorageMiner" "StorageMarket" "PaymentChannel" "MultisigAccount" |
| nonce | number Nonce is the nonce expected on the next message from this actor. Messages are processed in strict, contiguous nonce order. |
| balance | number Balance is the amount of FIL in the actor's account. |
| head | string The CID (Content Identifier) of the root of the Actor's state tree. |
| codeCid | string The CID (Content Identifier) of the VM code for this actor's implementation (or a constant for actors implemented in Go code). Code may be nil for an uninitialized actor (which exists because it has received a balance) |
| info | object or object or object or object or object |
An Ask is a price advertisement by a storage miner for storing data.
| id | string The ID of this Ask. |
| kind | string Value: "ask" |
| minerId | string The ID (address) of the miner Actor that published this Ask. |
| price | number The price in FIL per byte per blocktime being proposed in this Ask. |
| expiry | number The block height at which this Ask expires. |
A Block contains information relevant to a particular point in time over which the network may achieve consensus. Blocks are mined as part of the consensus mechanism by elected miners and then included in a Tipset.
See the BlockHeader Specificiation for more information.
| kind | string Value: "block" |
| id | string The CID (Content Identifier) of the Block |
| header | object (BlockHeader) |
| executedMessages | Array of objects (ExecutedMessage) |
A BlockHeader contains information relating to a Block. In the Filecoin specification there is no difference between a BlockHeader and a Block, but for the purposees of this API a Block wraps a BlockHeader and additionally contains the full contents of all messages included in that Block.
See the BlockHeader Specificiation for more information.
| kind | string Value: "blockHeader" |
| id | string The CID (Content Identifier) of the Block |
| height | number Height is the chain height of this block. |
| minerId | string The address of the miner Actor that mined this block. |
| messagesCid | string The CID (Content Identifier) of the of bls and secpk signed trees of Messages included in this Block. |
| receiptsCid | string The CID (Content Identifier) of the of tree containing receipts for the messages included in this block. Receipts are the return values and errors codes resulting from messages. |
| tickets | Array of objects |
| electionProof | string A base64 encoded byte array that represents the proof that the miner of this Block is a leader at this round. |
| parentTipsetId | string The ID of the Tipset on which this block was based. In the spec this field is defined as an array of Block IDs, which is effectively equivalent to a Tipset ID in this API. |
| parentWeight | number parentWeight is the aggregate chain weight (spec) of the parent Tipset. |
| stateRoot | string The CID (Content Identifier) of the root of the tree containing Actor state after the application of all the messages mined int his Block. |
| timestamp | number The block Timestamp is used to enforce a form of block delay by honest miners. Unix time UTC timestamp (in seconds) stored as an unsigned integer. |
| blsAggregate | string A base64 encoded representation of the aggregated BLS signature for all the messages in this block that were signed using BLS signatures |
| blockSig | string A base64 encoded representation of the signature over the hash of this entire block with the miner's worker key to ensure that it is not tampered with after creation |
| kind | string Value: "executedMessage" |
| id | string The CID (Content Identifier) of this ExecutedMessage |
| blockId | string The CID of the mined block that included this ExecutedMessage. |
| message | object (Message) |
| exitCode | number The exit value returned by the method this message was sent to. 0 is success, anything else is an error code in unix style. |
| return | object The base64 encoded return values, if any, from processing a message. This can be non-empty even in the case of error (e.g., to provide programmatically readable detail about errors). |
A Message is an exchange of information between two actors modeled as a function call. Messages are the equivalent of transactions in Ethereum.
See the Message Specification for more information.
| kind | string Value: "message" |
| id | string |
| nonce | number |
| from | string |
| to | string |
| value | number |
| gasPrice | number |
| gasLimit | number |
| method | string |
| parameters | object |
| signature | string |
| kind | string Value: "node" |
| id | string |
| addresses | Array of strings List of peer (network) addresses |
| version | string |
| commit | string |
| protocol | object |
| bitswapStats | object |
| config | object Full JSON representation of the node's current configuration |
A PaymentChannel is setup between actors in the Filecoin system to enable off-chain payments with on-chain guarantees, making settlement more efficient.
See the Payment Channel Actor Description for more information.
| id | string The ID of this PaymentChannel |
| kind | string Value: "paymentChannel" |
| targetActorId | string The address of the account to which funds will be transferred by this PaymentChannel upon successful redemption of vouchers |
| amount | number The total amount of FIL that is in this PaymentChannel and payable to the target |
| amountRedeemed | number The total amount of FIL that has already been transfered to the target. This value cannot ever exceed amount. |
| agreedEol | number The original chain height at which this PaymentChannel will expire. Specified upon creation and optionally extended by the creator of the channel. |
| actualEol | number The actual expiration for the payment PaymentChannel which can differ from agreedEol when the payment channel is in dispute |
| condition | object The condition specified in the most recent payment voucher for which a redemption attempt was made. |
| redeemed | boolean A flag indicated whether or not Redeem has been called on the payment PaymentChannel yet. This is necessary because AmountRedeemed can still be zero in the event of a zero-value voucher |
A StorageDeal represents the agreement between between two Actors; one Actor paying the other (via a PaymentChannel) to store data on their behalf.
See a description of how StorageDeals work in the Filecoin Storage Market Specification
| id | string The ID of this StorageDeal |
| kind | string Value: "storageDeal" |
| minerActorId | string The ID of the storage miner that is fulfilling this StorageDeal |
| clientActorId | string The ID of the client initiating the StorageDeal (will typically be the owner of the current node) |
| pieceId | string The ID of the Picee being stored |
| size | number Size of the Piece being stored in bytes |
| totalPrice | number The total price in FIL that will be paid for the entire storage operation |
| duration | number The duration of this StorageDeal in blocks |
| status | string Enum: "unknown" "rejected" "accepted" "started" "failed" "staged" "sealing" "complete" The current status of the StorageDeal |
| paymentInfo | object |
A TipSet is a set of blocks that have the same parent set and same number of tickets, which implies they will have been mined at the same height. A TipSet can contain multiple blocks if more than one miner successfully mines a block at the same height as another miner.
See the Tipset Specification and the [Tipset Description] in the consensus specification for more information
| kind | string Value: "tipset" |
| id | string |
| height | number |
| blocks | Array of objects (BlockHeader) |
| kind | string Value: "voucher" |
| paymentChannelId | string The ID of the PaymentChannel this Voucher is redeemable against. |
| payer | string The Actor ID (address) of the creator of the payment channel for this voucher. |
| target | string The Actor ID (address) of the recipient of the funds in this voucher. |
| amount | number The amount of FIL this Voucher is worth. This amount is sent to the target when this voucher is redeemed. |
| validAt | number The block height on or after which this Voucher can be redeemed. |
| condition | object The condition that must evaluate to true for this Voucher to be redeemed. |
| signature | string The signature over all the data in this Voucher |