Skip to content

Instantly share code, notes, and snippets.

@eingenito

eingenito/filecoin_http_api.markdown

Last active July 15, 2019 18:52
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save eingenito/caef478bd9e101768dbe628327c6f42f to your computer and use it in GitHub Desktop.
Save eingenito/caef478bd9e101768dbe628327c6f42f to your computer and use it in GitHub Desktop.
Download ZIP
Raw
filecoin_http_api.markdown
title weight menu
HTTP API
20
reference
parent
api

go-filecoin HTTP API

Overview

Alignment with CLI Commands

Every command usable from the CLI is also available through the HTTP API. For example:

> go-filecoin swarm peers
/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z

> curl http://127.0.0.1:3453/api/swarm/peers
{
  "Strings": [
    "/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
    "/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx",
    "/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
  ]
}

Arguments

Arguments are added through the special query string key "arg":

> curl "http://127.0.0.1:3453/api/swarm/disconnect?arg=/ip4/54.93.113.247/tcp/48131/ipfs/QmUDS3nsBD1X4XK5Jo836fed7SErTyTuQzRqWaiQAyBYMP"
{
  "Strings": [
    "disconnect QmUDS3nsBD1X4XK5Jo836fed7SErTyTuQzRqWaiQAyBYMP success",
  ]
}

Note that it can be used multiple times to signify multiple arguments.

Flags

Flags are added through the query string. For example, the %!s(MISSING) flag is the %!s(MISSING) query parameter below:

> curl "http://127.0.0.1:3453/api/object/get?arg=QmaaqrHyAQm7gALkRW8DcfGX3u8q9rWKnxEMmf7m9z515w&encoding=json"
{
  "Links": [
    {
      "Name": "index.html",
      "Hash": "QmYftndCvcEiuSZRX7njywX2AGSeHY2ASa7VryCq1mKwEw",
      "Size": 1700
    },
    {
      "Name": "static",
      "Hash": "QmdtWFiasJeh2ymW3TD2cLHYxn1ryTuWoNpwieFyJriGTS",
      "Size": 2428803
    }
  ],
  "Data": "CAE="
}

Index

Endpoints

/api/actor/ls

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "actorType": "<string>",
  "address": "<string>",
  "balance": "<object>",
  "code": {
    "/": "<cid-string>"
  },
  "exports": {
    "<string>": {
      "Params": [
        "<string>"
      ],
      "Return": [
        "<string>"
      ]
    }
  },
  "head": {
    "/": "<cid-string>"
  },
  "nonce": "<uint64>"
}

cURL Example

curl "http://localhost:3453/api/actor/ls"

/api/address/default

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Address": "<string>"
}

cURL Example

curl "http://localhost:3453/api/address/default"

/api/address/lookup

Arguments

  • arg [string]: Miner address to find peerId for Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<string>"

cURL Example

curl "http://localhost:3453/api/address/lookup?arg=<address>"

/api/address/ls

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Addresses": [
    "<string>"
  ]
}

cURL Example

curl "http://localhost:3453/api/address/ls"

/api/address/new

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Address": "<string>"
}

cURL Example

curl "http://localhost:3453/api/address/new"

/api/bitswap/stats

Show bitswap statistics.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "BlocksReceived": "<uint64>",
  "BlocksSent": "<uint64>",
  "DataReceived": "<uint64>",
  "DataSent": "<uint64>",
  "DupBlksReceived": "<uint64>",
  "DupDataReceived": "<uint64>",
  "MessagesReceived": "<uint64>",
  "Peers": [
    "<string>"
  ],
  "ProvideBufLen": "<int>",
  "Wantlist": [
    {
      "/": "<cid-string>"
    }
  ]
}

cURL Example

curl "http://localhost:3453/api/bitswap/stats"

/api/bootstrap/ls

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

cURL Example

curl "http://localhost:3453/api/bootstrap/ls"

/api/chain/head

Get heaviest tipset CIDs

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "/": "<cid-string>"
  }
]

cURL Example

curl "http://localhost:3453/api/chain/head"

/api/chain/ls

List blocks in the blockchain

Arguments

  • long [bool]: List blocks in long format, including CID, Miner, StateRoot, block height and message count respectively. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "height": "<object>",
    "messageReceipts": [
      {
        "exitCode": "<uint8>",
        "gasAttoFIL": "<object>",
        "return": [
          "<base64-string>"
        ]
      }
    ],
    "messages": [
      {
        "meteredMessage": {
          "gasLimit": "<object>",
          "gasPrice": "<object>",
          "message": {
            "from": "<object>",
            "method": "<string>",
            "nonce": "<object>",
            "params": "<base64-string>",
            "to": "<object>",
            "value": "<object>"
          }
        },
        "signature": [
          "<uint8>"
        ]
      }
    ],
    "miner": "<object>",
    "nonce": "<object>",
    "parentWeight": "<object>",
    "parents": "<object>",
    "proof": [
      "<uint8>"
    ],
    "stateRoot": {
      "/": "<cid-string>"
    },
    "ticket": [
      "<uint8>"
    ],
    "timestamp": "<object>"
  }
]

cURL Example

curl "http://localhost:3453/api/chain/ls?long=<value>"

/api/client/cat

Read out data stored on the network

Arguments

  • arg [string]: CID of data to read Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/client/cat?arg=<cid>"

/api/client/import

Import data into the local node

Arguments

  • arg [string]: Path to file to import Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "/": "<cid-string>"
}

cURL Example

curl "http://localhost:3453/api/client/import?arg=<file>"

/api/client/list-asks

List all asks in the storage market

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Error": "<error>",
  "Expiry": "<object>",
  "ID": "<uint64>",
  "Miner": "<object>",
  "Price": "<object>"
}

cURL Example

curl "http://localhost:3453/api/client/list-asks"

/api/client/payments

List payments for a given deal

Arguments

  • arg [string]: Channel id from which to list vouchers Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "amount": "<object>",
    "channel": "<object>",
    "condition": {
      "method": "<string>",
      "params": [
        "<object>"
      ],
      "to": "<object>"
    },
    "payer": "<object>",
    "signature": [
      "<uint8>"
    ],
    "target": "<object>",
    "valid_at": "<object>"
  }
]

cURL Example

curl "http://localhost:3453/api/client/payments?arg=<dealCid>"

/api/client/propose-storage-deal

Propose a storage deal with a storage miner

Arguments

  • arg [string]: Address of miner to send storage proposal Required: yes.
  • arg [string]: CID of the data to be stored Required: yes.
  • arg [string]: ID of ask for which to propose a deal Required: yes.
  • arg [string]: Time in blocks (about 30 seconds per block) to store data Required: yes.
  • allow-duplicates [bool]: Allows duplicate proposals to be created. Unless this flag is set, you will not be able to make more than one deal per piece per miner. This protection exists to prevent erroneous duplicate deals. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Message": "<string>",
  "ProofInfo": {
    "CommitmentMessage": {
      "/": "<cid-string>"
    },
    "PieceInclusionProof": "<base64-string>",
    "SectorID": "<uint64>"
  },
  "ProposalCid": {
    "/": "<cid-string>"
  },
  "Signature": [
    "<uint8>"
  ],
  "State": "<int>"
}

cURL Example

curl "http://localhost:3453/api/client/propose-storage-deal?arg=<miner>&arg=<data>&arg=<ask>&arg=<duration>&allow-duplicates=<value>"

/api/client/query-storage-deal

Query a storage deal's status

Arguments

  • arg [string]: CID of deal to query Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Message": "<string>",
  "ProofInfo": {
    "CommitmentMessage": {
      "/": "<cid-string>"
    },
    "PieceInclusionProof": "<base64-string>",
    "SectorID": "<uint64>"
  },
  "ProposalCid": {
    "/": "<cid-string>"
  },
  "Signature": [
    "<uint8>"
  ],
  "State": "<int>"
}

cURL Example

curl "http://localhost:3453/api/client/query-storage-deal?arg=<id>"

/api/config

Get and set filecoin config values

Arguments

  • arg [string]: The key of the config entry (e.g. "api.address") Required: yes.
  • arg [string]: Optionally, a value with which to set the config entry Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/config?arg=<key>&arg=<value>"

/api/daemon

Start a long-running daemon process

Arguments

  • swarmlisten [string]: multiaddress to listen on for filecoin network connections. Required: no.
  • swarmrelaypublic [string]: public multiaddress for routing circuit relay traffic. Necessary for relay nodes to provide this if they are not publically dialable. Required: no.
  • offline [bool]: start the node without networking. Required: no.
  • elstdout [bool]: Required: no.
  • is-relay [bool]: advertise and allow filecoin network traffic to be relayed through this node. Required: no.
  • block-time [string]: time a node waits before trying to mine the next block. Default: "30s". Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/daemon?swarmlisten=<value>&swarmrelaypublic=<value>&offline=<value>&elstdout=<value>&is-relay=<value>&block-time=30s"

/api/dag/get

Get a DAG node by its CID

Arguments

  • arg [string]: CID of object to get Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/dag/get?arg=<ref>"

/api/deals/list

List all deals

Arguments

  • client [bool]: only return deals made as a client. Required: no.
  • miner [bool]: only return deals made as a miner. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "minerAddress": "<object>",
  "pieceCid": {
    "/": "<cid-string>"
  },
  "proposalCid": {
    "/": "<cid-string>"
  },
  "state": "<string>"
}

cURL Example

curl "http://localhost:3453/api/deals/list?client=<value>&miner=<value>"

/api/deals/redeem

Redeem vouchers for a deal

Arguments

  • arg [string]: CID of the deal to redeem Required: yes.
  • from [string]: Address to send from. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/deals/redeem?arg=<dealid>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/deals/show

Show deal details for CID

Arguments

  • arg [string]: CID of deal to query Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "deal_cid": {
    "/": "<cid-string>"
  },
  "deal_size": "<object>",
  "duration_blocks": "<uint64>",
  "miner_address": "<object>",
  "payment_vouchers": [
    {
      "amount": "<object>",
      "channel_id": "<object>",
      "condition": {
        "method": "<string>",
        "params": [
          "<object>"
        ],
        "to": "<object>"
      },
      "encoded_as": "<string>",
      "index": "<uint64>",
      "payer": "<object>",
      "valid_at_block": "<object>"
    }
  ],
  "state": "<int>",
  "total_price": "<object>"
}

cURL Example

curl "http://localhost:3453/api/deals/show?arg=<cid>"

/api/dht/findpeer

Find the multiaddresses associated with a Peer ID.

Arguments

  • arg [string]: The ID of the peer to search for. Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/dht/findpeer?arg=<peerID>"

/api/dht/findprovs

Find peers that can provide a given key's value.

Arguments

  • arg [string]: The key whose provider Peer IDs are output. Required: yes.
  • verbose [bool]: Print extra information. Required: no.
  • num-providers [int]: The max number of providers to find. Default: "20". Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

cURL Example

curl "http://localhost:3453/api/dht/findprovs?arg=<key>&verbose=<value>&num-providers=20"

/api/dht/query

Find the closest Peer IDs to a given Peer ID by querying the DHT.

Arguments

  • arg [string]: The peerID to run the query against. Required: yes.
  • verbose [bool]: Print extra information. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

cURL Example

curl "http://localhost:3453/api/dht/query?arg=<peerID>&verbose=<value>"

/api/id

Show info about the network peers

Arguments

  • format [string]: Specify an output format. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<object>"

cURL Example

curl "http://localhost:3453/api/id?format=<value>"

/api/init

Initialize a filecoin repo

Arguments

  • genesisfile [string]: path of file or HTTP(S) URL containing archive of genesis block DAG data. Required: no.
  • peerkeyfile [string]: path of file containing key to use for new node's libp2p identity. Required: no.
  • with-miner [string]: when set, creates a custom genesis block with a pre generated miner account, requires running the daemon using dev mode (--dev). Required: no.
  • sectordir [string]: path of directory into which staged and sealed sectors will be written. Required: no.
  • default-address [string]: when set, sets the daemons's default address to the provided address. Required: no.
  • auto-seal-interval-seconds [uint]: when set to a number > 0, configures the daemon to check for and seal any staged sectors on an interval. Default: "120". Required: no.
  • devnet-test [bool]: when set, populates config bootstrap addrs with the dns multiaddrs of the test devnet and other test devnet specific bootstrap parameters. Required: no.
  • devnet-nightly [bool]: when set, populates config bootstrap addrs with the dns multiaddrs of the nightly devnet and other nightly devnet specific bootstrap parameters. Required: no.
  • devnet-user [bool]: when set, populates config bootstrap addrs with the dns multiaddrs of the user devnet and other user devnet specific bootstrap parameters. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/init?genesisfile=<value>&peerkeyfile=<value>&with-miner=<value>&sectordir=<value>&default-address=<value>&auto-seal-interval-seconds=120&devnet-test=<value>&devnet-nightly=<value>&devnet-user=<value>"

/api/inspect/all

Print all diagnostic information.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Config": {
    "api": {
      "accessControlAllowCredentials": "<bool>",
      "accessControlAllowMethods": [
        "<string>"
      ],
      "accessControlAllowOrigin": [
        "<string>"
      ],
      "address": "<string>"
    },
    "bootstrap": {
      "addresses": [
        "<string>"
      ],
      "minPeerThreshold": "<int>",
      "period": "<string>"
    },
    "datastore": {
      "path": "<string>",
      "type": "<string>"
    },
    "heartbeat": {
      "beatPeriod": "<string>",
      "beatTarget": "<string>",
      "nickname": "<string>",
      "reconnectPeriod": "<string>"
    },
    "mining": {
      "autoSealIntervalSeconds": "<uint>",
      "minerAddress": "<object>",
      "storagePrice": "<object>"
    },
    "mpool": {
      "maxNonceGap": "<object>",
      "maxPoolSize": "<uint>"
    },
    "net": "<string>",
    "observability": {
      "metrics": {
        "prometheusEnabled": "<bool>",
        "prometheusEndpoint": "<string>",
        "reportInterval": "<string>"
      },
      "tracing": {
        "jaegerEndpoint": "<string>",
        "jaegerTracingEnabled": "<bool>",
        "probabilitySampler": "<float64>"
      }
    },
    "sectorbase": {
      "rootdir": "<string>"
    },
    "swarm": {
      "address": "<string>",
      "public_relay_address": "<string>"
    },
    "wallet": {
      "defaultAddress": "<object>"
    }
  },
  "Disk": {
    "FSType": "<string>",
    "Free": "<uint64>",
    "Total": "<uint64>"
  },
  "Environment": {
    "FIL_API": "<string>",
    "FIL_PATH": "<string>",
    "GOPATH": "<string>"
  },
  "FilecoinVersion": "<string>",
  "Memory": {
    "Swap": "<uint64>",
    "Virtual": "<uint64>"
  },
  "Runtime": {
    "Arch": "<string>",
    "Compiler": "<string>",
    "GoMaxProcs": "<int>",
    "NumCGoCalls": "<int64>",
    "NumGoRoutines": "<int>",
    "NumProc": "<int>",
    "OS": "<string>",
    "Version": "<string>"
  }
}

cURL Example

curl "http://localhost:3453/api/inspect/all"

/api/inspect/config

Print in-memory config information.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "api": {
    "accessControlAllowCredentials": "<bool>",
    "accessControlAllowMethods": [
      "<string>"
    ],
    "accessControlAllowOrigin": [
      "<string>"
    ],
    "address": "<string>"
  },
  "bootstrap": {
    "addresses": [
      "<string>"
    ],
    "minPeerThreshold": "<int>",
    "period": "<string>"
  },
  "datastore": {
    "path": "<string>",
    "type": "<string>"
  },
  "heartbeat": {
    "beatPeriod": "<string>",
    "beatTarget": "<string>",
    "nickname": "<string>",
    "reconnectPeriod": "<string>"
  },
  "mining": {
    "autoSealIntervalSeconds": "<uint>",
    "minerAddress": "<object>",
    "storagePrice": "<object>"
  },
  "mpool": {
    "maxNonceGap": "<object>",
    "maxPoolSize": "<uint>"
  },
  "net": "<string>",
  "observability": {
    "metrics": {
      "prometheusEnabled": "<bool>",
      "prometheusEndpoint": "<string>",
      "reportInterval": "<string>"
    },
    "tracing": {
      "jaegerEndpoint": "<string>",
      "jaegerTracingEnabled": "<bool>",
      "probabilitySampler": "<float64>"
    }
  },
  "sectorbase": {
    "rootdir": "<string>"
  },
  "swarm": {
    "address": "<string>",
    "public_relay_address": "<string>"
  },
  "wallet": {
    "defaultAddress": "<object>"
  }
}

cURL Example

curl "http://localhost:3453/api/inspect/config"

/api/inspect/disk

Print filesystem usage information.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "FSType": "<string>",
  "Free": "<uint64>",
  "Total": "<uint64>"
}

cURL Example

curl "http://localhost:3453/api/inspect/disk"

/api/inspect/environment

Print filecoin environment information.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "FIL_API": "<string>",
  "FIL_PATH": "<string>",
  "GOPATH": "<string>"
}

cURL Example

curl "http://localhost:3453/api/inspect/environment"

/api/inspect/memory

Print memory usage information.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Swap": "<uint64>",
  "Virtual": "<uint64>"
}

cURL Example

curl "http://localhost:3453/api/inspect/memory"

/api/inspect/runtime

Print runtime diagnostic information.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Arch": "<string>",
  "Compiler": "<string>",
  "GoMaxProcs": "<int>",
  "NumCGoCalls": "<int64>",
  "NumGoRoutines": "<int>",
  "NumProc": "<int>",
  "OS": "<string>",
  "Version": "<string>"
}

cURL Example

curl "http://localhost:3453/api/inspect/runtime"

/api/log/level

Change the logging level.

Arguments

  • arg [string]: The log level, with 'debug' the most verbose and 'panic' the least verbose. One of: debug, info, warning, error, fatal, panic. Required: yes.
  • subsystem [string]: The subsystem logging identifier. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<string>"

cURL Example

curl "http://localhost:3453/api/log/level?arg=<level>&subsystem=<value>"

/api/log/ls

List the logging subsystems.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

[
  "<string>"
]

cURL Example

curl "http://localhost:3453/api/log/ls"

/api/log/tail

Read the event log.

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/log/tail"

/api/message/send

Send a message

Arguments

  • arg [string]: Address of the actor to send the message to Required: yes.
  • arg [string]: The method to invoke on the target actor Required: no.
  • value [string]: Value to send with message in FIL. Required: no.
  • from [string]: Address to send message from. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/message/send?arg=<target>&arg=<method>&value=<value>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/message/status

Show status of a message

Arguments

  • arg [string]: CID of the message to inspect Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "ChainMsg": {
    "Block": {
      "height": "<object>",
      "messageReceipts": [
        {
          "exitCode": "<uint8>",
          "gasAttoFIL": "<object>",
          "return": [
            "<base64-string>"
          ]
        }
      ],
      "messages": [
        {
          "meteredMessage": {
            "gasLimit": "<object>",
            "gasPrice": "<object>",
            "message": {
              "from": "<object>",
              "method": "<string>",
              "nonce": "<object>",
              "params": "<base64-string>",
              "to": "<object>",
              "value": "<object>"
            }
          },
          "signature": [
            "<uint8>"
          ]
        }
      ],
      "miner": "<object>",
      "nonce": "<object>",
      "parentWeight": "<object>",
      "parents": "<object>",
      "proof": [
        "<uint8>"
      ],
      "stateRoot": {
        "/": "<cid-string>"
      },
      "ticket": [
        "<uint8>"
      ],
      "timestamp": "<object>"
    },
    "Message": {
      "meteredMessage": {
        "gasLimit": "<object>",
        "gasPrice": "<object>",
        "message": {
          "from": "<object>",
          "method": "<string>",
          "nonce": "<object>",
          "params": "<base64-string>",
          "to": "<object>",
          "value": "<object>"
        }
      },
      "signature": [
        "<uint8>"
      ]
    },
    "Receipt": {
      "exitCode": "<uint8>",
      "gasAttoFIL": "<object>",
      "return": [
        "<base64-string>"
      ]
    }
  },
  "InOutbox": "<bool>",
  "InPool": "<bool>",
  "OnChain": "<bool>",
  "OutboxMsg": {
    "Msg": {
      "meteredMessage": {
        "gasLimit": "<object>",
        "gasPrice": "<object>",
        "message": {
          "from": "<object>",
          "method": "<string>",
          "nonce": "<object>",
          "params": "<base64-string>",
          "to": "<object>",
          "value": "<object>"
        }
      },
      "signature": [
        "<uint8>"
      ]
    },
    "Stamp": "<uint64>"
  },
  "PoolMsg": {
    "meteredMessage": {
      "gasLimit": "<object>",
      "gasPrice": "<object>",
      "message": {
        "from": "<object>",
        "method": "<string>",
        "nonce": "<object>",
        "params": "<base64-string>",
        "to": "<object>",
        "value": "<object>"
      }
    },
    "signature": [
      "<uint8>"
    ]
  }
}

cURL Example

curl "http://localhost:3453/api/message/status?arg=<cid>"

/api/message/wait

Wait for a message to appear in a mined block

Arguments

  • arg [string]: CID of the message to wait for Required: yes.
  • message [bool]: Print the whole message. Default: "true". Required: no.
  • receipt [bool]: Print the whole message receipt. Default: "true". Required: no.
  • return [bool]: Print the return value from the receipt. Default: "false". Required: no.
  • timeout [string]: Maximum time to wait for message. e.g., 300ms, 1.5h, 2h45m. Default: "10m". Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Message": {
    "meteredMessage": {
      "gasLimit": "<object>",
      "gasPrice": "<object>",
      "message": {
        "from": "<object>",
        "method": "<string>",
        "nonce": "<object>",
        "params": "<base64-string>",
        "to": "<object>",
        "value": "<object>"
      }
    },
    "signature": [
      "<uint8>"
    ]
  },
  "Receipt": {
    "exitCode": "<uint8>",
    "gasAttoFIL": "<object>",
    "return": [
      "<base64-string>"
    ]
  },
  "Signature": {
    "Params": [
      "<uint64>"
    ],
    "Return": [
      "<uint64>"
    ]
  }
}

cURL Example

curl "http://localhost:3453/api/message/wait?arg=<cid>&message=true&receipt=true&return=false&timeout=10m"

/api/miner/collateral

Get the active collateral of a miner

Arguments

  • arg [string]: The address of the miner Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<object>"

cURL Example

curl "http://localhost:3453/api/miner/collateral?arg=<miner>"

/api/miner/create

Create a new file miner with FIL

Arguments

  • arg [string]: The amount of collateral, in FIL. Required: yes.
  • sectorsize [string]: size of the sectors which this miner will commit, in bytes. Required: no.
  • from [string]: address to send from. Required: no.
  • peerid [string]: Base58-encoded libp2p peer ID that the miner will operate. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Address": "<object>",
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/miner/create?arg=<collateral>&sectorsize=<value>&from=<value>&peerid=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/miner/owner

Show the actor address of

Arguments

  • arg [string]: The address of the miner Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<object>"

cURL Example

curl "http://localhost:3453/api/miner/owner?arg=<miner>"

/api/miner/power

Get the power of a miner versus the total storage market power

Arguments

  • arg [string]: The address of the miner Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/miner/power?arg=<miner>"

/api/miner/set-price

Set the minimum price for storage

Arguments

  • arg [string]: The new price of storage in FIL per byte per block Required: yes.
  • arg [string]: How long this ask is valid for in blocks Required: yes.
  • from [string]: Address to send from. Required: no.
  • miner [string]: The address of the miner owning the ask. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "GasUsed": "<object>",
  "MinerSetPriceResponse": {
    "AddAskCid": {
      "/": "<cid-string>"
    },
    "BlockCid": {
      "/": "<cid-string>"
    },
    "MinerAddr": "<object>",
    "Price": "<object>"
  },
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/miner/set-price?arg=<storageprice>&arg=<expiry>&from=<value>&miner=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/miner/update-peerid

Change the libp2p identity that a miner is operating

Arguments

  • arg [string]: Miner address to update peer ID for Required: yes.
  • arg [string]: Base58-encoded libp2p peer ID that the miner will operate Required: yes.
  • from [string]: Address to send from. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/miner/update-peerid?arg=<address>&arg=<peerid>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/mining/once

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "/": "<cid-string>"
}

cURL Example

curl "http://localhost:3453/api/mining/once"

/api/mining/start

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<string>"

cURL Example

curl "http://localhost:3453/api/mining/start"

/api/mining/status

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Active": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/mining/status"

/api/mining/stop

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/mining/stop"

/api/mpool/ls

View the pool of outstanding messages

Arguments

  • wait-for-count [uint]: Block until this number of messages are in the pool. Default: "0". Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "meteredMessage": {
      "gasLimit": "<object>",
      "gasPrice": "<object>",
      "message": {
        "from": "<object>",
        "method": "<string>",
        "nonce": "<object>",
        "params": "<base64-string>",
        "to": "<object>",
        "value": "<object>"
      }
    },
    "signature": [
      "<uint8>"
    ]
  }
]

cURL Example

curl "http://localhost:3453/api/mpool/ls?wait-for-count=0"

/api/mpool/rm

Delete a message from the message pool

Arguments

  • arg [string]: The CID of the message to delete Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/mpool/rm?arg=<cid>"

/api/mpool/show

Show content of an outstanding message

Arguments

  • arg [string]: The CID of the message to show Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "meteredMessage": {
    "gasLimit": "<object>",
    "gasPrice": "<object>",
    "message": {
      "from": "<object>",
      "method": "<string>",
      "nonce": "<object>",
      "params": "<base64-string>",
      "to": "<object>",
      "value": "<object>"
    }
  },
  "signature": [
    "<uint8>"
  ]
}

cURL Example

curl "http://localhost:3453/api/mpool/show?arg=<cid>"

/api/outbox/clear

Clear the queue(s) of sent messages

Arguments

  • arg [string]: Address of the queue to clear (otherwise clears all) Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/outbox/clear?arg=<address>"

/api/outbox/ls

List the queue(s) of sent but un-mined messages

Arguments

  • arg [string]: Address of the queue to list (otherwise lists all) Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Address": "<object>",
  "Messages": [
    {
      "Msg": {
        "meteredMessage": {
          "gasLimit": "<object>",
          "gasPrice": "<object>",
          "message": {
            "from": "<object>",
            "method": "<string>",
            "nonce": "<object>",
            "params": "<base64-string>",
            "to": "<object>",
            "value": "<object>"
          }
        },
        "signature": [
          "<uint8>"
        ]
      },
      "Stamp": "<uint64>"
    }
  ]
}

cURL Example

curl "http://localhost:3453/api/outbox/ls?arg=<address>"

/api/paych/cancel

Cancel a payment channel early to recover funds

Arguments

  • arg [string]: id of channel to cancel Required: yes.
  • from [string]: address of the channel creator. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/paych/cancel?arg=<channel>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/paych/close

Redeem a payment voucher and close the payment channel

Arguments

  • arg [string]: Base58 encoded signed voucher Required: yes.
  • from [string]: Address of the channel target. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/paych/close?arg=<voucher>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/paych/create

Create a new payment channel

Arguments

  • arg [string]: Address of account that will redeem funds Required: yes.
  • arg [string]: Amount in FIL for the channel Required: yes.
  • arg [string]: The block height at which the channel should expire Required: yes.
  • from [string]: Address to send from. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/paych/create?arg=<target>&arg=<amount>&arg=<eol>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/paych/extend

Extend the value and lifetime of a given channel

Arguments

  • arg [string]: Id of channel to extend Required: yes.
  • arg [string]: Amount in FIL for the channel Required: yes.
  • arg [string]: The block height at which the channel should expire Required: yes.
  • from [string]: Address of the channel creator. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/paych/extend?arg=<channel>&arg=<amount>&arg=<eol>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/paych/ls

List all payment channels for a payer

Arguments

  • from [string]: Address for which message is sent. Required: no.
  • payer [string]: Address for which to retrieve channels (defaults to from if omitted). Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "<string>": {
    "agreed_eol": "<object>",
    "amount": "<object>",
    "amount_redeemed": "<object>",
    "condition": {
      "method": "<string>",
      "params": [
        "<object>"
      ],
      "to": "<object>"
    },
    "eol": "<object>",
    "redeemed": "<bool>",
    "target": "<object>"
  }
}

cURL Example

curl "http://localhost:3453/api/paych/ls?from=<value>&payer=<value>"

/api/paych/reclaim

Reclaim funds from an expired channel

Arguments

  • arg [string]: Id of channel from which funds are reclaimed Required: yes.
  • from [string]: Address of the channel creator. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/paych/reclaim?arg=<channel>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/paych/redeem

Redeem a payment voucher against a payment channel

Arguments

  • arg [string]: Base58 encoded signed voucher Required: yes.
  • from [string]: Address of the channel target. Required: no.
  • gas-price [string]: Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message. Required: no.
  • gas-limit [uint64]: Maximum number of GasUnits this message is allowed to consume. Required: no.
  • preview [bool]: Preview the Gas cost of this command without actually executing it. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "GasUsed": "<object>",
  "Preview": "<bool>"
}

cURL Example

curl "http://localhost:3453/api/paych/redeem?arg=<voucher>&from=<value>&gas-price=<value>&gas-limit=<value>&preview=<value>"

/api/paych/voucher

Create a new voucher from a payment channel

Arguments

  • arg [string]: Channel id of channel from which to create voucher Required: yes.
  • arg [string]: Amount in FIL of this voucher Required: yes.
  • from [string]: Address for which to retrieve channels. Required: no.
  • validat [string]: Smallest block height at which target can redeem. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/paych/voucher?arg=<channel>&arg=<amount>&from=<value>&validat=<value>"

/api/ping

Send echo request packets to p2p network members

Arguments

  • arg [string]: ID of peer to be pinged Required: yes.
  • count [uint]: Number of ping messages to send. Default: "0". Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Count": "<uint>",
  "Time": "<duration-ns>"
}

cURL Example

curl "http://localhost:3453/api/ping?arg=<peer ID>&count=0"

/api/protocol

Show protocol parameter details

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "AutoSealInterval": "<uint>",
  "BlockTime": "<duration-ns>",
  "ProofsMode": "<int>",
  "SupportedSectorSizes": [
    "<object>"
  ]
}

cURL Example

curl "http://localhost:3453/api/protocol"

/api/retrieval-client/retrieve-piece

Read out piece data stored by a miner on the network

Arguments

  • arg [string]: Retrieval miner actor address Required: yes.
  • arg [string]: Content identifier of piece to read Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

cURL Example

curl "http://localhost:3453/api/retrieval-client/retrieve-piece?arg=<miner>&arg=<cid>"

/api/show/block

Show a filecoin block by its CID

Arguments

  • arg [string]: CID of block to show Required: yes.
  • messages [bool]: show messages in block. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "height": "<object>",
  "messageReceipts": [
    {
      "exitCode": "<uint8>",
      "gasAttoFIL": "<object>",
      "return": [
        "<base64-string>"
      ]
    }
  ],
  "messages": [
    {
      "meteredMessage": {
        "gasLimit": "<object>",
        "gasPrice": "<object>",
        "message": {
          "from": "<object>",
          "method": "<string>",
          "nonce": "<object>",
          "params": "<base64-string>",
          "to": "<object>",
          "value": "<object>"
        }
      },
      "signature": [
        "<uint8>"
      ]
    }
  ],
  "miner": "<object>",
  "nonce": "<object>",
  "parentWeight": "<object>",
  "parents": "<object>",
  "proof": [
    "<uint8>"
  ],
  "stateRoot": {
    "/": "<cid-string>"
  },
  "ticket": [
    "<uint8>"
  ],
  "timestamp": "<object>"
}

cURL Example

curl "http://localhost:3453/api/show/block?arg=<cid>&messages=<value>"

/api/stats/bandwidth

View bandwidth usage metrics

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "RateIn": "<float64>",
  "RateOut": "<float64>",
  "TotalIn": "<int64>",
  "TotalOut": "<int64>"
}

cURL Example

curl "http://localhost:3453/api/stats/bandwidth"

/api/swarm/connect

Open connection to a given address.

Arguments

  • arg [string]: Address of peer to connect to. Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<peer-id>"

cURL Example

curl "http://localhost:3453/api/swarm/connect?arg=<address>"

/api/swarm/peers

List peers with open connections.

Arguments

  • verbose [bool]: Display all extra information. Required: no.
  • streams [bool]: Also list information about open streams for each peer. Required: no.
  • latency [bool]: Also list information about latency to each peer. Required: no.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    {
      "Addr": "<string>",
      "Latency": "<string>",
      "Muxer": "<string>",
      "Peer": "<string>",
      "Streams": [
        {
          "Protocol": "<string>"
        }
      ]
    }
  ]
}

cURL Example

curl "http://localhost:3453/api/swarm/peers?verbose=<value>&streams=<value>&latency=<value>"

/api/version

Show go-filecoin version information

Arguments

This endpoint takes no arguments.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Commit": "<string>"
}

cURL Example

curl "http://localhost:3453/api/version"

/api/wallet/balance

Arguments

  • arg [string]: Address to get balance for Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

"<object>"

cURL Example

curl "http://localhost:3453/api/wallet/balance?arg=<address>"

/api/wallet/export

Arguments

  • arg [string]: Addresses of keys to export Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "KeyInfo": [
    {
      "curve": "<string>",
      "privateKey": "<base64-string>"
    }
  ]
}

cURL Example

curl "http://localhost:3453/api/wallet/export?arg=<addresses>"

/api/wallet/import

Arguments

  • arg [string]: File containing wallet data to import Required: yes.

Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Addresses": [
    "<string>"
  ]
}

cURL Example

curl "http://localhost:3453/api/wallet/import?arg=<walletFile>"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment