Payment Assistant
Wire Binance Pay-style flows with shared HMAC client, QR parsing, and order state machine for send and receive scripts.
Overview
Payment Assistant is an agent skill most often used in Build (also Ship security, Operate monitoring) that provides Binance payment API client, HMAC signing, and order state management for send/receive flows.
Install
npx skills add https://github.com/binance/binance-skills-hub --skill payment-assistantWhat is this skill?
- OrderStatus state machine from INIT through QR_PARSED, POLLING, SUCCESS, and FAILED
- PaymentAPI with HMAC signing, rate limiting, and optional requests dependency guard
- Shared config load, validate, and guide paths for send.py and receive.py
- Typed models PaymentStatusResponse and ConfirmPaymentResponse for polling loops
- Centralized constants for paths, timing, error codes, and headers
- OrderStatus enum with 8 named states from INIT through FAILED
Adoption & trust: 1.8k installs on skills.sh; 881 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building Binance payment automation but lack a single module for config, signed requests, QR state, and polling-safe order transitions.
Who is it for?
Solo builders shipping Binance Pay integrations who need a documented state machine and shared Python infrastructure before custom UI.
Skip if: Builders who only need fiat card checkout without Binance APIs, or anyone unwilling to manage API secrets and payment compliance locally.
When should I use this skill?
Implementing or extending Binance payment send/receive scripts that need shared config, HMAC API client, and order state persistence.
What do I get? / Deliverables
Send and receive scripts share a validated PaymentAPI client and persisted OrderStatus transitions from QR through confirmed payment and final SUCCESS or FAILED.
- Validated payment configuration
- Signed API requests via PaymentAPI
- Persisted order state through terminal SUCCESS or FAILED
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because payment-assistant is shared infrastructure for implementing payment integrations, not production incident response alone. Integrations reflects API signing, QR workflows, and state persistence used by companion send/receive tooling.
Where it fits
Import PaymentAPI and OrderStatus while wiring send.py to confirm QR-based payments without duplicating HMAC logic.
Audit config validation and secret loading paths before exposing payment scripts to an automated agent with shell access.
Inspect persisted order state when a payment stalls in POLLING and you need FAILED versus SUCCESS reconciliation.
How it compares
Shared Python payment kernel for Binance flows, not a no-code payment widget or generic Stripe skill.
Common Questions / FAQ
Who is payment-assistant for?
It is for indie developers and agent authors implementing Binance payment send/receive automation with HMAC-signed API calls.
When should I use payment-assistant?
Use it in Build (integrations) while coding pay flows; in Ship (security) when reviewing secrets and signing; and in Operate (monitoring) when debugging stuck POLLING or FAILED order states.
Is payment-assistant safe to install?
It handles API keys and moves real payment state; review the Security Audits panel on this page and never commit secrets or run unreviewed scripts against production wallets.
SKILL.md
READMESKILL.md - Payment Assistant
#!/usr/bin/env python3 """ Payment Assistant - Common Infrastructure Shared by send.py and receive.py: - Constants (paths, timing, error codes, headers, config templates) - Configuration (load, validate, guide) - State management (OrderStatus, save/load/update/clear) - API client (PaymentAPI with HMAC signing, rate limiting) - Data models (PaymentStatusResponse, ConfirmPaymentResponse) """ import time import hmac import hashlib import os import json import secrets from typing import Dict, Any, Optional from enum import Enum try: import requests HAS_REQUESTS = True except ImportError: HAS_REQUESTS = False # ============================================================ # Order Status State Machine # ============================================================ class OrderStatus(Enum): """Order status for state machine tracking""" INIT = "INIT" # Initial state, QR received QR_PARSED = "QR_PARSED" # parseQr success, has preset amount AWAITING_AMOUNT = "AWAITING_AMOUNT" # Waiting for amount input (no preset) AMOUNT_SET = "AMOUNT_SET" # Amount set, ready to confirm PAYMENT_CONFIRMED = "PAYMENT_CONFIRMED" # confirmPayment called, polling POLLING = "POLLING" # Polling for result SUCCESS = "SUCCESS" # Payment successful FAILED = "FAILED" # Payment failed # ============================================================ # Skills Payment Error Codes # ============================================================ SKILLS_ERROR_CODES = { -7100: ('LIMIT_NOT_CONFIGURED', 'Please go to the Binance app payment setting page to set up your Agent Pay limits via MFA.'), -7101: ('SINGLE_LIMIT_EXCEEDED', 'Amount exceeds your limits. Please pay manually in the App.'), -7102: ('DAILY_LIMIT_EXCEEDED', 'Amount exceeds your limits. Please pay manually in the App.'), -7110: ('INSUFFICIENT_FUNDS', 'Insufficient balance in your Binance account.'), -7130: ('INVALID_QR_FORMAT', 'Invalid QR code format'), -7131: ('QR_EXPIRED_OR_NOT_FOUND', 'PayCode is invalid or expired. Please request a new one.'), -7199: ('INTERNAL_ERROR', 'System error, please try again later'), } # ============================================================ # Configuration # ============================================================ SKILL_DIR = os.path.dirname(os.path.abspath(__file__)) CONFIG_FILE_PATH = os.path.join(SKILL_DIR, 'config.json') STATE_FILE_PATH = os.path.join(SKILL_DIR, '.payment_state.json') API_LOCK_FILE_PATH = os.path.join(SKILL_DIR, '.api_lock_time') QR_CODE_OUTPUT_PATH = os.path.join(SKILL_DIR, 'payment_qr.png') INBOX_DIR = os.path.join(SKILL_DIR, 'inbox') CLIPBOARD_IMAGE_PATH = os.path.join(INBOX_DIR, 'qr_clipboard.png') # Timing configurations POLL_INTERVAL = 2 MAX_POLL_ATTEMPTS = 30 RECV_WINDOW = 30000 API_CALL_INTERVAL = 2.0 # OpenAPI Header names (for /binancepay/openapi/* endpoints) OPENAPI_HEADER_TIMESTAMP = 'BinancePay-Timestamp' OPENAPI_HEADER_NONCE = 'BinancePay-Nonce' OPENAPI_HEADER_CERT = 'BinancePay-Certificate-SN' OPENAPI_HEADER_SIGNATURE = 'BinancePay-Signature' # OpenAPI path prefix for routing OPENAPI_PATH_PREFIX = '/binancepay/openapi/' # API Key Setup Guide Message API_KEY_GUIDE_MESSAGE = 'Payment API key & secret not configured. Please set your API key & secret in Binance App first.' # Default config for auto-creation when config.json is missing DEFAULT_CONFIG_TEMPLATE = { "_comment_1": "=== Payment Assistant Configuration ===", "_comment_2": "Please fill in the required fields below and set 'configured' to true", "_comment_3": "---", "configured": False, "_comment_api_key": "API Key: Please set your API key & secret in Binance App first", "api_key": "", "_comment_api_secret": "API Secret: Generated together with API Key, keep it safe!", "api_secret": "", "_comment_5": "--- After filling in, set 'configured'