Skip to main content

Wallet Foreign API

The Foreign API is the side of the wallet other people call. A sender posts a slate to it and gets back a partially signed one, a payer's invoice comes back finalised, and a mining node asks it to build the coinbase output that pays this wallet.

  • Endpoint: http://127.0.0.1:3415/v2/foreign, started with epic-wallet listen
  • Protocol: JSON-RPC 2.0 over HTTP POST
  • Credential: none
  • Default bind: api_listen_interface is 127.0.0.1 and api_listen_port is 3415 (config/src/types.rs:71)

No credential is possible here, because the counterparty completing a transfer is a stranger who must be able to reach the surface. The default bind is loopback, so a counterparty reaching this wallet over HTTP needs the interface widened or a reverse proxy in front of it, and whatever is in front is the only place access can be restricted. Taking delivery over the epicbox relay instead needs no inbound port at all.

The same six methods are served from the owner listener when owner_api_include_foreign is true (controller/src/controller.rs:151).

Endpoint
http://127.0.0.1:3415/v2/foreign
Credential
None. This is what a counterparty pays you through
Methods here
6
Documented against
node 4.0.3, wallet 4.0.0

check_version

Read only

Report the Foreign API and supported slate versions.

Surface
/v2/foreign on port 3415
Parameters
none
Declared in
api/src/foreign_rpc.rs:65

This method takes no parameters.

6 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "check_version",
  "params": []
}
Response
N/A

build_coinbase

Changes state

Build a coinbase output and kernel for a candidate block.

Surface
/v2/foreign on port 3415
Parameters
1 positional
Declared in
api/src/foreign_rpc.rs:116
Parameters

Candidate block fees, height and optional key id.

12 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "build_coinbase",
  "params": [
    {
      "fees": 0,
      "height": 1,
      "key_id": null
    }
  ]
}
Response
N/A

build_foundation

Changes state

Build the foundation output and kernel for a candidate block.

Surface
/v2/foreign on port 3415
Parameters
1 positional
Declared in
api/src/foreign_rpc.rs:119
Parameters

Candidate block fees, height and optional key id.

12 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "build_foundation",
  "params": [
    {
      "fees": 0,
      "height": 1,
      "key_id": null
    }
  ]
}
Response
N/A

verify_slate_messages

Read only

Verify message signatures attached to a slate.

Surface
/v2/foreign on port 3415
Parameters
1 positional
Declared in
api/src/foreign_rpc.rs:201
Parameters

Slate containing participant messages.

8 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "verify_slate_messages",
  "params": [
    {}
  ]
}
Response
N/A

receive_tx

Changes state

Add the listener wallet output and signature to an incoming slate.

Surface
/v2/foreign on port 3415
Parameters
4 positional
Declared in
api/src/foreign_rpc.rs:359
Parameters

Incoming slate.

Account to receive into.

Recipient message.

Sender address.

11 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "receive_tx",
  "params": [
    {},
    null,
    null,
    null
  ]
}
Response
N/A

finalize_invoice_tx

Changes state

Finalize an invoice slate after the payer has funded it.

Surface
/v2/foreign on port 3415
Parameters
1 positional
Declared in
api/src/foreign_rpc.rs:532
Parameters

Funded invoice slate.

8 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "finalize_invoice_tx",
  "params": [
    {}
  ]
}
Response
N/A

Source​

Next​

Interactive transactions

What the two rounds are, and which side does what.

Transports

How a slate reaches this surface in the first place.

Authentication and TLS

Every surface and the credential it expects.