coreth/plugin/evm/api.md at main

mirror of https://github.com/luxfi/coreth.git synced 2026-10-30 17:00:51 +00:00

Files

T

zeekay cc8e370005 docs: chain routes are /v1/chain

luxd serves chain APIs under one segment from constants.ChainAliasPrefix
(constants v1.6.4, node v1.36.181):

  /v1/bc/<alias>/...   -> /v1/chain/<alias>/...
  /ext/bc/<alias>/...  -> /v1/chain/<alias>/...

Observations keep their original addresses: a dated note or a recorded status
code is a fact about when it was written, not an instruction to follow.

2026-08-30 17:11:49 -07:00

9.2 KiB

Raw Permalink Blame History

title, description

title	description
C-Chain API	This page is an overview of the C-Chain API associated with Luxd.

Ethereum has its own notion of `networkID` and `chainID`. These have no relationship to Lux's view of networkID and chainID and are purely internal to the [C-Chain](/docs/quick-start/primary-network#c-chain). On Mainnet, the C-Chain uses `1` and `43114` for these values. On the Testnet Testnet, it uses `1` and `43113` for these values. `networkID` and `chainID` can also be obtained using the `net_version` and `eth_chainId` methods.

Ethereum APIs

Endpoints

JSON-RPC Endpoints

To interact with C-Chain via the JSON-RPC endpoint:

/v1/chain/C/rpc

To interact with other instances of the EVM via the JSON-RPC endpoint:

/v1/chain/blockchainID/rpc

where blockchainID is the ID of the blockchain running the EVM.

WebSocket Endpoints

On the [public API node](/docs/tooling/rpc-providers), it only supports C-Chain websocket API calls for API methods that don't exist on the C-Chain's HTTP API

To interact with C-Chain via the websocket endpoint:

/v1/chain/C/ws

For example, to interact with the C-Chain's Ethereum APIs via websocket on localhost, you can use:

ws://127.0.0.1:9650/v1/chain/C/ws

<Callout title="Tip" icon = {} > On localhost, use ws://. When using the Public API or another host that supports encryption, use wss://.

To interact with other instances of the EVM via the websocket endpoint:

/v1/chain/blockchainID/ws

where blockchainID is the ID of the blockchain running the EVM.

Standard Ethereum APIs

Lux offers an API interface identical to Geth's API except that it only supports the following services:

web3_
net_
eth_
personal_
txpool_
debug_ (note: this is turned off on the public API node.)

You can interact with these services the same exact way you'd interact with Geth (see exceptions below). See the Ethereum Wiki's JSON-RPC Documentation and Geth's JSON-RPC Documentation for a full description of this API.

For batched requests on the [public API node](/docs/tooling/rpc-providers) , the maximum number of items is 40.

Exceptions

Starting with release v0.12.2, eth_getProof has a different behavior compared to geth:

On archival nodes (nodes withpruning-enabled set to false), queries for state proofs older than 24 hours preceding the last accepted block will be rejected by default. This can be adjusted with historical-proof-query-window, which defines the number of blocks before the last accepted block that can be queried for state proofs. Set this option to 0 to accept a state query for any block number.
On pruning nodes (nodes with pruning-enabled set to true), queries for state proofs outside the 32 block window after the last accepted block are always rejected.

Lux - Ethereum APIs

In addition to the standard Ethereum APIs, Lux offers eth_baseFee, eth_maxPriorityFeePerGas, and eth_getChainConfig.

They use the same endpoint as standard Ethereum APIs:

/v1/chain/C/rpc

`eth_baseFee`

Get the base fee for the next block.

Signature:

eth_baseFee() -> {}

result is the hex value of the base fee for the next block.

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_baseFee",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/rpc

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x34630b8a00"
}

`eth_maxPriorityFeePerGas`

Get the priority fee needed to be included in a block.

Signature:

eth_maxPriorityFeePerGas() -> {}

result is hex value of the priority fee needed to be included in a block.

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_maxPriorityFeePerGas",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/rpc

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2540be400"
}

For more information on dynamic fees see the C-Chain section of the transaction fee documentation.

Admin APIs

The Admin API provides administrative functionality for the EVM.

Endpoint

/v1/chain/C/admin

Methods

`admin_startCPUProfiler`

Starts a CPU profile that writes to the specified file.

Signature:

admin_startCPUProfiler() -> {}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_startCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/admin

`admin_stopCPUProfiler`

Stops the CPU profile.

Signature:

admin_stopCPUProfiler() -> {}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_stopCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/admin

`admin_memoryProfile`

Runs a memory profile writing to the specified file.

Signature:

admin_memoryProfile() -> {}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_memoryProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/admin

`admin_lockProfile`

Runs a mutex profile writing to the specified file.

Signature:

admin_lockProfile() -> {}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_lockProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/admin

`admin_setLogLevel`

Sets the log level for the EVM.

Signature:

admin_setLogLevel({
    level: string
}) -> {}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_setLogLevel",
    "params" :[{
        "level": "debug"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/admin

`admin_getVMConfig`

Returns the current VM configuration.

Signature:

admin_getVMConfig() -> {
    config: {
        // VM configuration fields
    }
}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_getVMConfig",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/admin

Lux-Specific APIs

Endpoint

/v1/chain/C/lux

Methods

`lux.getUTXOs`

Gets all UTXOs for the specified addresses.

Signature:

lux.getUTXOs({
    addresses: [string],
    sourceChain: string,
    startIndex: {
        address: string,
        utxo: string
    },
    limit: number,
    encoding: string
}) -> {
    utxos: [string],
    endIndex: {
        address: string,
        utxo: string
    },
    numFetched: number,
    encoding: string
}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getUTXOs",
    "params" :[{
        "addresses": ["X-lux1..."],
        "sourceChain": "X",
        "limit": 100,
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/lux

`lux.issueTx`

Issues a transaction to the network.

Signature:

lux.issueTx({
    tx: string,
    encoding: string
}) -> {
    txID: string
}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.issueTx",
    "params" :[{
        "tx": "0x...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/lux

`lux.getAtomicTxStatus`

Returns the status of the specified atomic transaction.

Signature:

lux.getAtomicTxStatus({
    txID: string
}) -> {
    status: string,
    blockHeight: number (optional)
}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getAtomicTxStatus",
    "params" :[{
        "txID": "2QouvNW..."
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/lux

`lux.getAtomicTx`

Returns the specified atomic transaction.

Signature:

lux.getAtomicTx({
    txID: string,
    encoding: string
}) -> {
    tx: string,
    encoding: string,
    blockHeight: number (optional)
}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getAtomicTx",
    "params" :[{
        "txID": "2QouvNW...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/lux

`lux.version`

Returns the version of the VM.

Signature:

lux.version() -> {
    version: string
}

Example Call:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.version",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/v1/chain/C/lux

9.2 KiB Raw Permalink Blame History

Ethereum APIs

Endpoints

JSON-RPC Endpoints

WebSocket Endpoints

Standard Ethereum APIs

Exceptions

Lux - Ethereum APIs

eth_baseFee

eth_maxPriorityFeePerGas

Admin APIs

Endpoint

Methods

admin_startCPUProfiler

admin_stopCPUProfiler

admin_memoryProfile

admin_lockProfile

admin_setLogLevel

admin_getVMConfig

Lux-Specific APIs

Endpoint

Methods

lux.getUTXOs

lux.issueTx

lux.getAtomicTxStatus

lux.getAtomicTx

lux.version

9.2 KiB

Raw Permalink Blame History

`eth_baseFee`

`eth_maxPriorityFeePerGas`

`admin_startCPUProfiler`

`admin_stopCPUProfiler`

`admin_memoryProfile`

`admin_lockProfile`

`admin_setLogLevel`

`admin_getVMConfig`

`lux.getUTXOs`

`lux.issueTx`

`lux.getAtomicTxStatus`

`lux.getAtomicTx`

`lux.version`