{"id":22072556,"url":"https://github.com/broxus/ever-wallet-api","last_synced_at":"2025-07-24T11:30:40.269Z","repository":{"id":41094758,"uuid":"410013989","full_name":"broxus/ever-wallet-api","owner":"broxus","description":"Self-hosted wallet management service","archived":false,"fork":false,"pushed_at":"2024-10-29T11:36:53.000Z","size":1439,"stargazers_count":22,"open_issues_count":1,"forks_count":20,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-29T13:25:55.424Z","etag":null,"topics":["blockcain","everscale","venom-blockchain","venom-developer-program","venom-wallet","web3"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/broxus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-24T15:28:32.000Z","updated_at":"2024-10-29T11:37:01.000Z","dependencies_parsed_at":"2024-02-02T13:56:23.481Z","dependency_job_id":"f67daa51-03a5-4a4b-a9d5-251b9e718d19","html_url":"https://github.com/broxus/ever-wallet-api","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fever-wallet-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fever-wallet-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fever-wallet-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fever-wallet-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/broxus","download_url":"https://codeload.github.com/broxus/ever-wallet-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227432007,"owners_count":17775893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockcain","everscale","venom-blockchain","venom-developer-program","venom-wallet","web3"],"created_at":"2024-11-30T21:13:41.739Z","updated_at":"2024-11-30T21:13:42.364Z","avatar_url":"https://github.com/broxus.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/venom-blockchain/developer-program\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/venom-blockchain/developer-program/main/vf-dev-program.png\" alt=\"Logo\" width=\"366.8\" height=\"146.4\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003ch3 align=\"center\"\u003eEverscale Wallet API\u003c/h3\u003e\n    \u003cp align=\"center\"\u003e\n        \u003ca href=\"/LICENSE\"\u003e\n            \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/broxus/octusbridge-relay\" /\u003e\n        \u003c/a\u003e\n    \u003c/p\u003e\n\u003c/p\u003e\n\n### Overview\nThis is a light node + api for sending and tracking payments. The app listens for addresses from the database and\nindexes all transactions, putting information about them in the postsgres DB. All transactions with native EVERs are\ntracked, and there is a whitelist of root token addresses to be tracked in the settings. There is a callbacks table\nin the database, where you can specify the url of your backend to which callbacks will come for all transactions.\n\nIt takes about 20 minutes to synchronize the node.\nBoth the ton-wallet-api and callback requests use HMAC signatures in the headers.\n\n### Runtime requirements\n- CPU: 4 cores, 2 GHz\n- RAM: 8 GB\n- Storage: 100 GB fast SSD\n- Network: 100 MBit/s\n- Postgres: 11 or higher\n\n### How to run natively\n\nTo simplify the build and create some semblance of standardization in this repository\nthere is a set of scripts for configuring the ton-wallet-api.\n\nNOTE: scripts are prepared and tested on **Ubuntu 20.04**. You may need to modify them a little for other distros.\n\n1. ##### Setup ton-wallet-api service\n   ```bash\n   ./scripts/setup.sh -t native --database-url ${DATABASE_URL}\n   ```\n\n   DATABASE_URL - Postgres connection url (example: postgresql://postgres:postgres@127.0.0.1/ton_wallet_api)\n\n   \u003e At this stage, a systemd service `ton-wallet-api` is created. Configs and keys will be in `/etc/ton-wallet-api`\n   \u003e and TON node DB will be in `/var/db/ton-wallet-api`.\n\n   **Do not start this service yet!**\n\n2. ##### Prepare config\n   Either add the environment variables to the `[Service]` section of unit file.\n   It is located at `/etc/systemd/system/ton-wallet-api.service`.\n\n   ```unit file (systemd)\n   [Service]\n   ...\n   Environment=DB_HOST=db_host\n   Environment=DB_USER=db_user\n   Environment=DB_PASSWORD=db_password\n   Environment=DB_NAME=ton_wallet_api\n   Environment=SECRET=secret\n   Environment=SALT=salt\n   ...\n   ```\n\n   \u003e SECRET - any string to encrypt/decrypt all addresses private keys.\n\n   \u003e SALT - 16 bytes recommended in B64 for secret hashing.\n\n   ###### How to gen SALT\n   ```bash\n   cargo build --release\n   ./target/release/ton-wallet-api salt\n   ```\n\n3. ##### Create api service\n   ```bash\n     ./scripts/api_service.sh -t native --database-url ${DATABASE_URL} --id ${SERVICE_ID} --name ${SERVICE_NAME} --key ${SERVICE_KEY} --secret ${SERVICE_SECRET}\n   ```\n\n   DATABASE_URL - Postgres connection url (example: postgresql://postgres:postgres@127.0.0.1/ton_wallet_api) \\\n   SERVICE_ID - Service id (UUID4) (example: 1fa337bd-2947-4809-9a7a-f04b4f9b738a) \\\n   SERVICE_NAME - Service name (example: test) \\\n   SERVICE_KEY - Public key (example: apiKey) \\\n   SERVICE_SECRET - Secret key (example: apiSecret)\n\n4. ##### Enable and start ton-wallet-api service\n   ```bash\n   systemctl enable ton-wallet-api\n   systemctl start ton-wallet-api\n\n   # Optionally check if it is running normally. It will take some time to start.\n   # ton-wallet-api is fully operational when it prints `listening on ${your_listen_address}`\n   journalctl -fu ton-wallet-api\n   ```\n\n   \u003e Wallet API has a two built-in Prometheus metrics exporters: API and Node.\n   \u003e You can enable API metrics by giving the value of api_metrics_addr in config.\n   \u003e Node metrics exporter is configured in the `node_metrics_settings` section of the config.\n   \u003e By default, node metrics are available at `http://127.0.0.1:10000/`\n   \u003e\n   \u003e \u003cdetails\u003e\u003csummary\u003e\u003cb\u003eNode metrics response example:\u003c/b\u003e\u003c/summary\u003e\n   \u003e \u003cp\u003e\n   \u003e\n   \u003e ```\n   \u003e ton_subscriber_ready 1\n   \u003e ton_subscriber_current_utime 1639490380\n   \u003e ton_subscriber_time_diff 4\n   \u003e ton_subscriber_shard_client_time_diff 7\n   \u003e ton_subscriber_mc_block_seqno 13179326\n   \u003e ton_subscriber_shard_client_mc_block_seqno 13179326\n   \u003e ton_subscriber_pending_message_count 0\n   \u003e ```\n   \u003e\n   \u003e \u003c/p\u003e\n   \u003e \u003c/details\u003e\n\n5. ##### Update service\n   ```bash\n     ./scripts/update.sh -t native --database-url ${DATABASE_URL}\n   ```\n\n   DATABASE_URL - Postgres connection url (example: postgresql://postgres:postgres@127.0.0.1/ton_wallet_api)\n\n\n### Let's start using Wallet API\n\n1. #### Create address\n   Create yourself a \"system address\" by calling `/address/create` with empty parameters. The response will return a EVER\n   address. It is necessary to send EVERs on it, which will be consumed as gas for further work.\n   \n   **For simplicity, you use the script**\n\n   ```bash\n   API_KEY=${API_KEY} SECRET=${API_SECRET} HOST=${HOST} \\\n   ./scripts/wallet.sh -m create_account\n   ```\n\n2. #### Callbacks\n   In the table `api_service_callback` we enter the address of our backend, which will deal with payment processing.\n   After receiving or sending new transactions or token transactions Wallet API will call web hook with POST method on\n   `callback` url. Body will contain `AccountTransactionEvent` from [swagger](https://tonapi.broxus.com/swagger.yaml).\n\n3. #### Token Whitelist\n   You can see the root-contract addresses at [manifest](https://raw.githubusercontent.com/broxus/ton-assets/master/manifest.json).\n   By default, the whitelist already includes all the tokens in this list.\n\n   To add more tokens to the whitelist, use the script:\n   ```bash\n     ./scripts/root_token.sh -t native --database-url ${DATABASE_URL} --name ${TOKEN_NAME} --address ${TOKEN_ADDRESS} --version ${TOKEN_CONTRACT_VERSION}\n   ```\n   \n   DATABASE_URL - Postgres connection url (example: postgresql://postgres:postgres@127.0.0.1/ton_wallet_api) \\\n   TOKEN_NAME - Token name (example: WTON) \\\n   TOKEN_ADDRESS - Token address (example: 0:0ee39330eddb680ce731cd6a443c71d9069db06d149a9bec9569d1eb8d04eb37)\n   TOKEN_CONTRACT_VERSION - \"Tip3\" or \"OldTip3v4\"\n\n4. #### Transfer EVER\n   Example request:\n   ```\n   /transactions/create\n   {\n      // a random uuid that you generate yourself and store on your backend, to further track the status of the transaction\n      \"id\":\"00000000-0000-0000-0000-000000000000\",\n      // The address of the sender. For example, your system address.\n      \"fromAddress\":\"0:0000000000000000000000000000000000000000000000000000000000000000\",\n      \"bounce\":false,\n      \"outputs\":[\n         {\n            // how much EVER to send. To send 1 EVER this value = 1000000000\n            \"value\":\"1000000000\",\n            // Set Normal to take the number of sent EVERs from the value\n            \"outputType\":\"Normal\",\n            // Recipient address of EVERs\n            \"recipientAddress\":\"0:0000000000000000000000000000000000000000000000000000000000000000\"\n         }\n      ],\n      // base64 encoded payload\n      payload: \"te6ccgEBAQEABgAACAVriBQ=\"\n   }\n   ```\n   Or use the script:\n   ```bash\n   # Create transaction\n   API_KEY=${API_KEY} SECRET=${API_SECRET} HOST=${HOST} \\\n   ./scripts/wallet.sh -m create_transaction \\\n   --src-addr {sender} --dst-addr {recipient} --amount {amount}\n   ```\n   \n   You can track the status of a transaction with:\n   1) (Recommended way) via callback `AccountTransactionEvent`, which has transactionStatus field:\n      * `expired` - end state for failed transactions,\n      * `done` - final state for successful transactions. \n      \n      If your backend was disabled during the callback or responded with an error, the event will have an `Error` state.\n      In this case you should query all events `/events` in `Error` state at backend startup, process them and give each\n      event a `Done` state by calling `/events/mark`.\n   2) by polling the GET method `/transactions/id/\u003cuuid\u003e`\n\n5. #### How to process a payment from a user on the backend\n   We generate a deposit address for the user by calling `/address/create` with empty parameters. After receiving the\n   payment, the backend receives a callback of the form `AccountTransactionEvent` (see [swagger](https://tonapi.broxus.com/swagger.yaml)).\n   You can also get such events in a list, using the /events method.\n\n   If your backend was not working at the time of the callback or responded with an error, the event will have an\n   `Error` status. In this case you should query all events `/events` in `Error` state at the start of the backend, process\n   them and set each of them to `Done` state by calling `/events/mark`. Each event has an id (generated by ton-api). You\n   can do extra checks on it to make sure that your backend doesn't re-process events.\n\n6. #### Transfer tokens\n   First, check the status and balance of the address you want to send tokens from by making a GET request to /address/{string}.\n   The address you are sending tokens from must have at least 0.6 EVER (balance \u003e= 600000000).\n\n   To transfer tokens, use the method:\n   ```\n   /tokens/transactions/create\n   {\n      // a random uuid that you generate yourself and store on your backend, to further track the status of the transaction\n      \"id\":\"00000000-0000-0000-0000-000000000000\",\n      // The address of the sender. For example, your system address.\n      \"fromAddress\":\"0:0000000000000000000000000000000000000000000000000000000000000000\",\n      // Recipient address of EVERs\n      \"recipientAddress\":\"0:0000000000000000000000000000000000000000000000000000000000000000\",\n      // The number of tokens with decimals. For example, for transferring 1 USDT this value = \"1000000\"\n      \"value\":\"1000000000\",\n      // How much to apply EVER, the default recommended value is 0.5 EVER. The funds will be debited fromAddress.\n      \"fee\": \"5000000000\",\n      // The address to which to return the residuals EVER. For example, your system address.\n      \"sendGasTo\":\"0:0000000000000000000000000000000000000000000000000000000000000000\",\n      // Token Address from whitelist\n      \"rootAddress\":\"0:0000000000000000000000000000000000000000000000000000000000000000\",\n      // base64 encoded payload\n      \"payload\": \"te6ccgEBAQEABgAACAVriBQ=\"\n   }\n   ```\n   Or use the script:\n   ```bash\n    # Create token transaction\n   API_KEY=${API_KEY} SECRET=${API_SECRET} HOST=${HOST} \\\n   ./scripts/wallet.sh -m create_token_transaction \\\n   --src-addr {sender} --dst-addr {recipient} \\\n   --root-addr {root_token_address} --amount {amount}\n   ```\n\n   You can track the status of a transaction with:\n   1) (Recommended way) via callback `AccountTransactionEvent`, which has `transactionStatus` field:\n      * `expired` - end state for failed transactions,\n      * `done` - final state for successful transactions.\n\n      If your backend was down at the time of the callback or responded with an error, the event will have an `Error` state.\n      In this case, you should query all events `/token/events` in Error state at backend startup, process them, and set\n      each event to `Done` state by calling `/token/events/mark`.\n\n   2) by polling with the GET method `/tokens/transactions/id/\u003cuuid\u003e`\n\n\n### Postman\n[pre-request-script.js](scripts/pre-request-script.js) is javascript for using with Postman's pre-request script \nfeature. It generates HTTP request headers for HMAC authentication. Copy the contents of \n[pre-request-script.js](scripts/pre-request-script.js) into the \"Pre-request Script\" tab in Postman to send signed \nrequest.\n\n### Authorization signatures\n\nA request must undergo an authorization step, which involves verifying the request payload, URI, and timestamp \nagainst a known secret specific to each service. For GET requests, the body is empty, while for POST requests, \nthe body is a string representing the serialized JSON payload. The payload must be pretty-printed (stored) with an \nindentation of 4 spaces. An example of the string to be signed is provided below. This setup generally applies to POST \nrequests.\n\n```bash\nstringToSign=\"$timestamp$uri$body\"\necho -en \"$stringToSign\" | openssl sha256 -hmac \"$secret\" -binary | base64\n```\n\n### Example config\n\n\u003e NOTE: The syntax `${VAR}` can also be used everywhere in config. It will be\n\u003e replaced by the value of the environment variable `VAR`.\n\n```yaml\n---\n# Server address\nserver_addr: \"0.0.0.0:8080\"\n# Database URL\ndatabase_url: \"postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}/${DB_NAME}\"\n# Database Connection Pools\ndb_pool_size: 5\nton_core:\n  # UDP port, used for ADNL node. Default: 30303\n  adnl_port: 30303\n  # Root directory for ton-wallet-api DB. Default: \"./db\"\n  db_path: \"/var/ton-wallet-api/db\"\n  # Path to ADNL keys.\n  # NOTE: Will be generated if it was not there.\n  # Default: \"./adnl-keys.json\"\n  keys_path: \"/var/ton-wallet-api/adnl-keys.json\"\nmetrics_settings:\n  # Listen address of metrics. Used by the client to gather prometheus metrics.\n  # Default: \"127.0.0.1:10000\"\n  listen_address: \"127.0.0.1:10000\"\n  # URL path to the metrics. Default: \"/\"\n  # Example: `curl http://127.0.0.1:10000/`\n  metrics_path: \"/\"\n  # Metrics update interval in seconds. Default: 10\n  collection_interval_sec: 10\n# log4rs settings.\n# See https://docs.rs/log4rs/1.0.0/log4rs/ for more details\nlogger_settings:\n  appenders:\n    stdout:\n      kind: console\n      encoder:\n        pattern: \"{d(%Y-%m-%d %H:%M:%S %Z)(utc)} - {h({l})} {M} = {m} {n}\"\n  root:\n    level: error\n    appenders:\n      - stdout\n  loggers:\n    ton_wallet_api:\n      level: info\n      appenders:\n        - stdout\n      additive: false\n    ton_indexer:\n      level: error\n      appenders:\n        - stdout\n      additive: false\n```\n\n### How to Run via Docker/Podman\n\nThis guide explains how to build and run the project using Podman (or Docker as an alternative). \nThere are two Dockerfiles: one for building an intermediate image for setting and compiling the Rust project and \nanother for deploying it. With that user may replace configuration files and start parameters and promptly rebuild\ndeployment image.\n\n#### Prerequisites\n\nUser must provide a link to running Postgres instance with user and password. It will be used for migrations and for \ndeployment as well.\n\n#### Building Images\n\nTo build the images, two Dockerfiles are used: `builder.dockerfile` for compiling the project and `deploy.dockerfile` \nfor setting up the deployment environment.\n\n1. **Build the builder image**:\n   The `builder.dockerfile` is responsible for compiling the project using Rust. It builds the project based on the \n   specified network (either `everscale` or `venom`) and prepares the database for the application using SQLx.\n\n   Use the following command to build the builder image:\n\n   ```bash\n   podman build --layers --network=host -f builder.dockerfile -t builder --build-arg DATABASE_URL=\"postgresql://everscale:everscale@localhost:5432/everscale\"\n   ```\n\n2. **Build the deployment image**:\n   The `deploy.dockerfile` is used to create the runtime environment and copy the necessary binaries and configuration \n   files from the `builder` stage.\n\n   Build the deployment image using the following command:\n\n   ```bash\n   podman build --layers -f deploy.dockerfile -t ever-wallet\n   ```\n\n#### Running the Container\n\nOnce the images are built, you can run the container using Podman or Docker.\n\n1. **Running the application**:\n\n   To run the application, use the following command:\n\n   ```bash\n   podman run --network=host ever-wallet\n   ```\n\n   This will run the `ton-wallet-api` server using the default configuration files already existing in the container.\n   Errors shall be expected at this step.\n\n   ```bash\n   WARN: Environment variable DB_USER was not set\n   WARN: Environment variable DB_PASSWORD was not set\n   WARN: Environment variable DB_HOST was not set\n   WARN: Environment variable DB_NAME was not set\n   ```\n\n   To avoid these errors, the database connection and other settings (such as secrets) shall be provided. \n   Alternatively, they may be added into `deploy.dockerfile`. For example:\n\n   ```bash\n   podman run --network=host \\\n     -v /tmp/everscale-data:/var/db/ton-wallet-api\n     -e DB_USER=everscale \\\n     -e DB_PASSWORD=everscale \\\n     -e DB_HOST=localhost \\\n     -e DB_NAME=everscale \\\n     -e SECRET=0xAAAAA \\\n     -e SALT=OreOYYe5nHWTHnOPSvsmMQ \\\n     ever-wallet\n   ```\n\n   It generally allows dynamically setting environment variables for database credentials, secrets, and other \n   configurations.\n\n### Troubleshooting\n\nWhen the node is out of sync, which especially applies for Venom, removing database and re-syncing node may help to\nrestore service operations.\n\n`rm -rf /var/db/ton-wallet-api`\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbroxus%2Fever-wallet-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbroxus%2Fever-wallet-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbroxus%2Fever-wallet-api/lists"}