1. Introduction

This document contains generated documentation for AMPnet blockchain-api-service. Blockchain API service provides endpoints to verify user wallet ownership as well as endpoints to fetch data from blockchain for verified wallets. Source code is available on Github.

2. ERC20 Balance Checking API

All endpoints are public and do not require Authorization: Bearer JWT header.

2.1. Create ERC20 Balance Check Request

Creates ERC20 balance request with specified parameters. Either client_id or chain_id, redirect_url and token_address must be provided as request body parameters. block_number, wallet_address, arbitrary_data, screen_config and all its child fields are optional. arbitrary_data field can contain any desired JSON value. Balance check request ID can be interpolated into the redirect_url by placing ${id} placeholder in the place where request ID is desired in the URL. The placeholder must strictly have dollar sign and brackets to be interpolated, and only id field can be interpolated.

Example request using client_id field:

Request
POST /balance HTTP/1.1
Content-Type: application/json
Content-Length: 303
Host: localhost:8080

{
  "client_id" : "client-id",
  "block_number" : "10",
  "wallet_address" : "0x000000000000000000000000000000000000000a",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  }
}
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: 656

{
  "id" : "3216c9ee-88dd-4e15-a15e-9c588f2aa161",
  "status" : "PENDING",
  "chain_id" : 31337,
  "redirect_url" : "https://example.com/3216c9ee-88dd-4e15-a15e-9c588f2aa161",
  "token_address" : "0x00000000000000000000000000000000cafebabe",
  "block_number" : "10",
  "wallet_address" : "0x000000000000000000000000000000000000000a",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  },
  "balance" : null,
  "message_to_sign" : "Verification message ID to sign: 3216c9ee-88dd-4e15-a15e-9c588f2aa161",
  "signed_message" : null
}

Example request using chain_id, redirect_url and token_address fields:

Request
POST /balance HTTP/1.1
Content-Type: application/json
Content-Length: 410
Host: localhost:8080

{
  "chain_id" : 31337,
  "redirect_url" : "https://example.com/${id}",
  "token_address" : "0x00000000000000000000000000000000cafebabe",
  "block_number" : "10",
  "wallet_address" : "0x000000000000000000000000000000000000000a",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  }
}
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: 656

{
  "id" : "d7480545-878d-4d67-8fb1-91140a4dd7b0",
  "status" : "PENDING",
  "chain_id" : 31337,
  "redirect_url" : "https://example.com/d7480545-878d-4d67-8fb1-91140a4dd7b0",
  "token_address" : "0x00000000000000000000000000000000cafebabe",
  "block_number" : "10",
  "wallet_address" : "0x000000000000000000000000000000000000000a",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  },
  "balance" : null,
  "message_to_sign" : "Verification message ID to sign: d7480545-878d-4d67-8fb1-91140a4dd7b0",
  "signed_message" : null
}

2.2. Fetch ERC20 Balance Check Request by ID

Fetches stored ERC20 balance check request with its current status. Possible statuses are PENDING, SUCCESS and FAILED. The request is considered successful if the attached signed message is valid and was signed by wallet_address. If wallet_address was not specified when the request was created, then any valid signature will be accepted. For successful requests, balance field will contain info about requested ERC20 balance. For pending requests, balance and signed_message fields will always be null. If the signed message is invalid or does not match specified wallet_address, request will be considered as failed. If block_number was specified during request creation, then ERC20 balance will be fetched only for that block number, and if block_number was not specified then the latest ERC20 balance will be fetched every time this resource is requested.

Custom RPC URL can be specified via optional X-RPC-URL header - this will NOT override the default RPC URL for the specified chain ID, it only allows you to specify RPC URL for non-natively supported chains. To override the default RPC URL, use X-RPC-URL-OVERRIDE header.

Request
GET /balance/7d86b0ac-a9a6-40fc-ac6d-2a29ca687f73 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: 938

{
  "id" : "7d86b0ac-a9a6-40fc-ac6d-2a29ca687f73",
  "status" : "SUCCESS",
  "chain_id" : 31337,
  "redirect_url" : "https://example.com/7d86b0ac-a9a6-40fc-ac6d-2a29ca687f73",
  "token_address" : "0x56f7dc1cc938d6d6575b68d70d381f9c28c8c7b7",
  "block_number" : "9",
  "wallet_address" : "0x865f603f42ca1231e5b5f90e15663b0fe19f0b21",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  },
  "balance" : {
    "wallet" : "0x865f603f42ca1231e5b5f90e15663b0fe19f0b21",
    "block_number" : "9",
    "timestamp" : "2022-05-16T10:01:56Z",
    "amount" : "10000"
  },
  "message_to_sign" : "Verification message ID to sign: 7d86b0ac-a9a6-40fc-ac6d-2a29ca687f73",
  "signed_message" : "0xfc90c8aa9f2164234b8826144d8ecfc287b5d7c168d0e9d284baf76dbef55c4c5761cf46e34b7cdb72cc97f1fb1c19f315ee7a430dd6111fa6c693b41c96c5501c"
}

2.3. Attach WalletAddress and Signed Message to ERC20 Balance Check Request

Attaches wallet address and signed message to existing ERC20 balance check request. Once the wallet address and signed message are attached to the request, any subsequent attempts to attach a new values will fail.

Request
PUT /balance/932e65a3-122f-4cab-b8e2-6407a020f4c1 HTTP/1.1
Content-Type: application/json
Content-Length: 108
Host: localhost:8080

{
  "wallet_address" : "0x000000000000000000000000000000000000000c",
  "signed_message" : "signed-message"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
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

3. ERC20 Send Request API

All endpoints are public and do not require Authorization: Bearer JWT header.

3.1. Create ERC20 Send Request

Creates ERC20 send request with specified parameters. Either client_id or chain_id, redirect_url and token_address must be provided as request body parameters. sender_address, arbitrary_data, screen_config and all its child fields are optional. arbitrary_data field can contain any desired JSON value. Send request ID can be interpolated into the redirect_url by placing ${id} placeholder in the place where request ID is desired in the URL. The placeholder must strictly have dollar sign and brackets to be interpolated, and only id field can be interpolated.

Example request using client_id field:

Request
POST /send HTTP/1.1
Content-Type: application/json
Content-Length: 367
Host: localhost:8080

{
  "client_id" : "client-id",
  "amount" : "10",
  "sender_address" : "0x000000000000000000000000000000000000000b",
  "recipient_address" : "0x000000000000000000000000000000000000000c",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  }
}
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: 1117

{
  "id" : "39ebd6db-de5e-4a86-a006-fe967c84c4dd",
  "status" : "PENDING",
  "chain_id" : 31337,
  "token_address" : "0x00000000000000000000000000000000cafebabe",
  "amount" : "10",
  "sender_address" : "0x000000000000000000000000000000000000000b",
  "recipient_address" : "0x000000000000000000000000000000000000000c",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  },
  "redirect_url" : "https://example.com/39ebd6db-de5e-4a86-a006-fe967c84c4dd",
  "send_tx" : {
    "tx_hash" : null,
    "from" : "0x000000000000000000000000000000000000000b",
    "to" : "0x00000000000000000000000000000000cafebabe",
    "data" : "0xa9059cbb000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000002433396562643664622d646535652d346138362d613030362d66653936376338346334646400000000000000000000000000000000000000000000000000000000",
    "block_confirmations" : null
  }
}

Example request using chain_id, redirect_url and token_address fields:

Request
POST /send HTTP/1.1
Content-Type: application/json
Content-Length: 474
Host: localhost:8080

{
  "chain_id" : 31337,
  "redirect_url" : "https://example.com/${id}",
  "token_address" : "0x000000000000000000000000000000000000000a",
  "amount" : "10",
  "sender_address" : "0x000000000000000000000000000000000000000b",
  "recipient_address" : "0x000000000000000000000000000000000000000c",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  }
}
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: 1117

{
  "id" : "d3a5d78e-de69-4be3-bbf7-f40bf2b7b50e",
  "status" : "PENDING",
  "chain_id" : 31337,
  "token_address" : "0x000000000000000000000000000000000000000a",
  "amount" : "10",
  "sender_address" : "0x000000000000000000000000000000000000000b",
  "recipient_address" : "0x000000000000000000000000000000000000000c",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  },
  "redirect_url" : "https://example.com/d3a5d78e-de69-4be3-bbf7-f40bf2b7b50e",
  "send_tx" : {
    "tx_hash" : null,
    "from" : "0x000000000000000000000000000000000000000b",
    "to" : "0x000000000000000000000000000000000000000a",
    "data" : "0xa9059cbb000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000002464336135643738652d646536392d346265332d626266372d66343062663262376235306500000000000000000000000000000000000000000000000000000000",
    "block_confirmations" : null
  }
}

3.2. Fetch ERC20 Send Request by ID

Fetches stored ERC20 send request with its current status. Possible statuses are PENDING, SUCCESS and FAILED. The request is considered successful if the attached transaction is confirmed on blockchain and all its data matches specified request parameters (correct to and from addresses, amount, matching data and txHash). If there are any mismatches between specified request data and state on blockchain, the request will be marked as failed. If there is no attached transaction hash or if transaction for attached hash is not yet mined on blockchain, request will be in pending state.

Custom RPC URL can be specified via optional X-RPC-URL header - this will NOT override the default RPC URL for the specified chain ID, it only allows you to specify RPC URL for non-natively supported chains. To override the default RPC URL, use X-RPC-URL-OVERRIDE header.

Request
GET /send/2155f4ec-e1c3-486b-b335-bcaacefa50f8 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: 1179

{
  "id" : "2155f4ec-e1c3-486b-b335-bcaacefa50f8",
  "status" : "FAILED",
  "chain_id" : 31337,
  "token_address" : "0xb5ae3e2883934457cb593793f034b401867e1372",
  "amount" : "10",
  "sender_address" : "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1",
  "recipient_address" : "0x4e90a36b45879f5bae71b57ad525e817afa54890",
  "arbitrary_data" : {
    "test" : true
  },
  "screen_config" : {
    "before_action_message" : "before-action-message",
    "after_action_message" : "after-action-message"
  },
  "redirect_url" : "https://example.com/2155f4ec-e1c3-486b-b335-bcaacefa50f8",
  "send_tx" : {
    "tx_hash" : "0xced84754b07f693c7ea57a7e606f5af97e40a6212a09a3f921b08c96330a3d32",
    "from" : "0x959fd7ef9089b7142b6b908dc3a8af7aa8ff0fa1",
    "to" : "0xb5ae3e2883934457cb593793f034b401867e1372",
    "data" : "0xa9059cbb0000000000000000000000004e90a36b45879f5bae71b57ad525e817afa54890000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000002432313535663465632d653163332d343836622d623333352d62636161636566613530663800000000000000000000000000000000000000000000000000000000",
    "block_confirmations" : "4"
  }
}

3.3. Attach Transaction Hash to ERC20 Send Request

Attaches transaction hash to existing ERC20 send request. Once the transaction hash is attached to the request, any subsequent attempts to attach a new transaction hash will fail.

Request
PUT /send/e7212746-9f55-4045-91f3-5c3f2cde5070 HTTP/1.1
Content-Type: application/json
Content-Length: 27
Host: localhost:8080

{
  "tx_hash" : "tx-hash"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
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