1. Introduction

This document contains generated documentation for AMPnet payout-service. Payout service contains all endpoints for managing payouts to asset holders. Source code is available on Github.

2. Payout Info API

All endpoints are public and do not require Authorization: Bearer JWT header. Chain ID (e.g. 80001) and asset contract address must be provided in the request path.

2.1. Get payout Merkle tree

Fetches the entire Merkle tree for the payout with specified parameters. Path arguments in order are: chain ID, asset contract address, Merkle tree root hash.

Request
GET /payout_info/31337/0x5bf28a1e60eb56107fad2de1f2aa51fc7a60c690/tree/0x0449524a95f9c3b8a3f89876d0ddd69917f8993f641ea9e8614c470c6bf7e897 HTTP/1.1
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 485

{
  "merkle_tree" : {
    "depth" : 1,
    "hash" : "0x0449524a95f9c3b8a3f89876d0ddd69917f8993f641ea9e8614c470c6bf7e897",
    "hash_fn" : "KECCAK_256",
    "left" : {
      "hash" : "0x0000000000000000000000000000000000000000000000000000000000000000"
    },
    "right" : {
      "hash" : "0x99237419f13d684e6b0dbeed5ad434eb2e0c2276d247cdcb482226ebdbbf09ff",
      "data" : {
        "address" : "0x8f52b0cc50967fc59c6289f8fdb3e356edeebd23",
        "balance" : "1"
      }
    }
  }
}

2.2. Get payout Merkle tree path for account

Fetches the Merkle tree path for the payout with specified parameters for specified wallet address. Path arguments in order are: chain ID, asset contract address, Merkle tree root hash, wallet address.

Request
GET /payout_info/31337/0x5bf28a1e60eb56107fad2de1f2aa51fc7a60c690/tree/0x0449524a95f9c3b8a3f89876d0ddd69917f8993f641ea9e8614c470c6bf7e897/path/0x8f52b0cc50967fc59c6289f8fdb3e356edeebd23 HTTP/1.1
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 315

{
  "wallet_address" : "0x8f52b0cc50967fc59c6289f8fdb3e356edeebd23",
  "wallet_balance" : "1",
  "path" : [ {
    "sibling_hash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
    "is_left" : true
  } ],
  "proof" : [ "0x0000000000000000000000000000000000000000000000000000000000000000" ]
}

3. Snapshot API

All endpoint require Authorization: Bearer JWT header.

3.1. Submit create snapshot request

Requests creation of ERC20 snapshot Merkle tree for specified parameters. This endpoint will return snapshot ID which can then be used to fetch snapshot info via another endpoint.

Request
POST /snapshots HTTP/1.1
Content-Type: application/json
Content-Length: 277
Host: localhost:8080

{
  "name" : "snapshot-name",
  "chain_id" : 31337,
  "asset_address" : "0xe7fd76d12c91d68121e178c77590becea5a8d832",
  "payout_block_number" : "73",
  "ignored_holder_addresses" : [ "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1", "0x301e1528bad61177ef8ff89bd4ad6760581e5409" ]
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 51

{
  "id" : "58dedd6a-22b4-444e-bdb2-3575e6612aa4"
}

3.2. Fetch snapshot

Fetches info about stored snapshot by ID. Possible snapshot statuses are PENDING, SUCCESS and FAILED. Possible failure causes are LOG_RESPONSE_LIMIT and OTHER. Single path argument is the snapshot ID.

Request
GET /snapshots/effbff61-b50b-4385-b973-1a2a93189e8e HTTP/1.1
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 657

{
  "id" : "effbff61-b50b-4385-b973-1a2a93189e8e",
  "name" : "snapshot-name",
  "chain_id" : 31337,
  "status" : "SUCCESS",
  "failure_cause" : null,
  "owner" : "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1",
  "asset" : "0xa0590e2f8878fc9190c7e967e5ac0958f0b08069",
  "total_asset_amount" : "600",
  "ignored_holder_addresses" : [ "0x301e1528bad61177ef8ff89bd4ad6760581e5409", "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1" ],
  "asset_snapshot_merkle_root" : "0x3ac65938baf45936b0ec984cdf7dbf4fd3a57cc18f5ee33791fe8d669f74fc1d",
  "asset_snapshot_merkle_depth" : 2,
  "asset_snapshot_block_number" : "45",
  "asset_snapshot_merkle_ipfs_hash" : "test-hash"
}

3.3. Fetch list of snapshots

Fetches all snapshots for the requesting user and specified filters. Possible snapshot statuses are PENDING, SUCCESS and FAILED. Possible failure causes are LOG_RESPONSE_LIMIT and OTHER. Available query parameters are chainId and status and both are optional. Multiple values can be specified for status query parameter by separating them with commas. Requesting user is specified implicitly via the Authorization: Bearer JWT header.

Request
GET /snapshots?status=PENDING,SUCCESS,FAILED&chainId=31337 HTTP/1.1
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 709

{
  "snapshots" : [ {
    "id" : "31918c7d-4831-4c9c-97d7-c2ac4a4cced7",
    "name" : "snapshot-name",
    "chain_id" : 31337,
    "status" : "SUCCESS",
    "failure_cause" : null,
    "owner" : "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1",
    "asset" : "0xb5ae3e2883934457cb593793f034b401867e1372",
    "total_asset_amount" : "600",
    "ignored_holder_addresses" : [ "0x301e1528bad61177ef8ff89bd4ad6760581e5409", "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1" ],
    "asset_snapshot_merkle_root" : "0x3ac65938baf45936b0ec984cdf7dbf4fd3a57cc18f5ee33791fe8d669f74fc1d",
    "asset_snapshot_merkle_depth" : 2,
    "asset_snapshot_block_number" : "13",
    "asset_snapshot_merkle_ipfs_hash" : "test-hash"
  } ]
}

4. Claimable Payouts API

All endpoint require Authorization: Bearer JWT header.

4.1. Fetch list of claimable payouts for investor

Fetches claimable and claimed payouts for an investor. Available query parameters are: chainId, assetFactories, payoutService, payoutManager and issuer. All query parameters are mandatory except issuer. Multiple values for assetFactories query parameter can be specified by separating them with commas. Claimable payouts will also contain proof necessary to claim them via the payout manager contract.

Request
GET /claimable_payouts?chainId=31337&assetFactories=0x0000000000000000000000000000000000000001&payoutService=0x0843a79f4ac84bf406d74b8bca7a5bcbaf6f43c0&payoutManager=0xa0590e2f8878fc9190c7e967e5ac0958f0b08069&issuer=0x1bc7b42173c68073ff168c53a667e0ad2952897b HTTP/1.1
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1152

{
  "claimable_payouts" : [ {
    "payout" : {
      "payout_id" : "0",
      "payout_owner" : "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1",
      "payout_info" : "payout-info",
      "is_canceled" : false,
      "asset" : "0x50d75c1bc6a1ce35002c9f92d0af4b3684aa6b74",
      "total_asset_amount" : "600",
      "ignored_holder_addresses" : [ "0x301e1528bad61177ef8ff89bd4ad6760581e5409", "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1" ],
      "asset_snapshot_merkle_root" : "0x3ac65938baf45936b0ec984cdf7dbf4fd3a57cc18f5ee33791fe8d669f74fc1d",
      "asset_snapshot_merkle_depth" : 2,
      "asset_snapshot_block_number" : "12",
      "asset_snapshot_merkle_ipfs_hash" : "test-hash",
      "reward_asset" : "0x0000000000000000000000000000000000123456",
      "total_reward_amount" : "60000",
      "remaining_reward_amount" : "60000"
    },
    "investor" : "0x4e90a36b45879f5bae71b57ad525e817afa54890",
    "amount_claimed" : "0",
    "amount_claimable" : "10000",
    "balance" : "100",
    "proof" : [ "0x2d1c16044c1356518f69628db82774a5b1966ba94369b80ed9a7145b92e18120", "0x886b363035ea0461a5f24cc74febb9d9eef43a3cb6fa9d1ee55c25e3532f3333" ]
  } ]
}