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