API: Wallet

Read your balance and history and start a top-up.

Balances are returned in Rial. A top-up returns a bank page address that a person must open in a browser to pay.

Get add-on prices

GET /service-prices

Returns the prices of the paid add-ons: floating IP per item, data disk and snapshots per GB, each for one 30-day period, in USD-equivalent and in Rial at today's rate.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK

Example

curl -X GET https://veneshcloud.ir/api/service-prices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Wallet balance

GET /wallet

Returns your balance in Rial.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK. Returns WalletBalance.

Example

curl -X GET https://veneshcloud.ir/api/wallet \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Transaction history

GET /wallet/ledger

Returns your wallet movements, newest first, paginated.

Authentication: Send your API key or token as a bearer token.

Query parameters

Field	Type	Values
`per_page`	integer

Responses

200 OK. Returns: data (list of WalletLedgerEntry).

Example

curl -X GET https://veneshcloud.ir/api/wallet/ledger \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Download an invoice as PDF

GET /invoices/{id}/pdf

Returns one of your invoices as a PDF file, in the language of the request.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`id`	integer

Query parameters

Field	Type	Values
`locale`	string	`fa`, `en`

Responses

200 OK
404 Not found

Example

curl -X GET https://veneshcloud.ir/api/invoices/KEY_ID/pdf \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Invoices and receipts

GET /wallet/invoices

Returns the same records shaped as invoices, with Rial amounts.

Authentication: Send your API key or token as a bearer token.

Query parameters

Field	Type	Values
`per_page`	integer

Responses

200 OK. Returns: data (list of Invoice).

Example

curl -X GET https://veneshcloud.ir/api/wallet/invoices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

USDT top-up availability

GET /wallet/crypto/options

Tells you whether top-up with USDT is available, which networks are open (TRON TRC20, Ethereum ERC20 and, once switched on, BNB Smart Chain BEP20) and the minimum amount.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK. Returns: enabled (boolean), card_enabled (boolean), network (string), network_label (string), currency (string), networks (list of CryptoNetwork), default_network (string), min_usdt (string), expiry_minutes (integer).

Example

curl -X GET https://veneshcloud.ir/api/wallet/crypto/options \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

List USDT networks

GET /wallet/crypto/networks

Returns the open networks with an estimated network fee (what the sender pays the chain, in TRX, ETH or BNB; never added to the USDT amount) and an estimated time. The fee is an estimate and can be missing: your wallet decides the final fee.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK. Returns: data (list of CryptoNetwork).

Example

curl -X GET https://veneshcloud.ir/api/wallet/crypto/networks \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Quote a USDT top-up

GET /wallet/crypto/quote

Converts a Rial amount (amount_rial) or a USDT amount (amount_usdt) to the USDT base amount at the current rate. Pass network (tron, ethereum or bsc) to include that network's service fee. Returns 404 when USDT top-up is off.

Authentication: Send your API key or token as a bearer token.

Query parameters

Field	Type	Values
`amount_rial`	integer
`amount_usdt`	string
`network`	string	`tron`, `ethereum`, `bsc`

Responses

200 OK. Returns: network (string), base_usdt (string), service_fee (string), amount_before_suffix (string), usd_equivalent (string), rial_amount (integer), effective_rate (string), fx_rate_id (integer), min_usdt (string), below_minimum (boolean).
404 Not found
503 Temporarily unavailable

Example

curl -X GET https://veneshcloud.ir/api/wallet/crypto/quote \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

List your USDT invoices

GET /wallet/crypto/invoices

Returns your most recent USDT top-up invoices.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK. Returns: data (list of CryptoInvoice).

Example

curl -X GET https://veneshcloud.ir/api/wallet/crypto/invoices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Create a USDT top-up invoice

POST /wallet/crypto/invoices

Creates an invoice for the chosen network (tron, ethereum or bsc) with the exact amount to send (top-up amount plus our service fee, if any, plus a few matching digits), the receiving address, the estimated network fee and time, and an expiry. Send exactly that amount on that network; the wallet is credited automatically once the transfer has enough confirmations. The address, token contract and chain are always set by the server, and a transaction ID can never be submitted by the client.

Authentication: Send your API key or token as a bearer token.

Request body (application/json)

Field	Type	Required	Values
`amount_rial`	integer	No
`amount_usdt`	string	No
`network`	string	No	`tron`, `ethereum`, `bsc`

Responses

201 Created. Returns: data (CryptoInvoice).
404 Not found
422 Validation error, or not allowed in the current state
429 Too many requests
503 Temporarily unavailable

Example

curl -X POST https://veneshcloud.ir/api/wallet/crypto/invoices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Get a USDT invoice

GET /wallet/crypto/invoices/{id}

Returns one of your invoices and its status (pending, detected, confirming, paid, expired, manual_review, cancelled), with the confirmations so far (timing), the estimated network fee and the exchange rate it was created with (effective_rate, Rial per US dollar). Safe to poll every 5 to 10 seconds.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`id`	integer

Responses

200 OK. Returns: data (CryptoInvoice).
404 Not found

Example

curl -X GET https://veneshcloud.ir/api/wallet/crypto/invoices/KEY_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Refresh the network fee estimate

POST /wallet/crypto/invoices/{id}/refresh-fee

Re-estimates only the network fee and time of one of your open invoices. The amount to send never changes. Limited to 12 calls a minute.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`id`	integer

Responses

200 OK. Returns: data (CryptoInvoice).
404 Not found

Example

curl -X POST https://veneshcloud.ir/api/wallet/crypto/invoices/KEY_ID/refresh-fee \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Cancel a USDT invoice

POST /wallet/crypto/invoices/{id}/cancel

Cancels one of your open invoices so you can start a new one. Do not send money for a cancelled invoice: if a transfer still arrives it is not credited automatically and is reviewed by our team first.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`id`	integer

Responses

200 OK. Returns: data (CryptoInvoice).
404 Not found
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/wallet/crypto/invoices/KEY_ID/cancel \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Start a top-up

POST /wallet/topup

Creates a top-up and returns redirect_url, the bank payment page. Open it in a browser to pay; the bank then returns the person to the site.

Authentication: Send your API key or token as a bearer token.

Request body (application/json)

Field	Type	Required	Values
`amount_rial`	integer	Yes

Responses

200 OK. Returns: topup_id (integer), redirect_url (string).
422 Validation error, or not allowed in the current state
502 Provider error
503 Temporarily unavailable

Example

curl -X POST https://veneshcloud.ir/api/wallet/topup \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount_rial":<AMOUNT_IN_RIAL>}'

Objects

Field lists for the objects returned above.

CryptoInvoice

Field	Type	Values
`id`	integer
`status`	string	`pending`, `detected`, `confirming`, `paid`, `expired`, `manual_review`, `cancelled`
`currency`	string
`network`	object
`network_label`	string
`token`	object
`token_contract`	string
`address`	string
`amount`	string
`base_amount`	string
`pricing`	object
`received_amount`	string
`usd_equivalent`	string
`rial_amount`	integer
`network_fee`	`CryptoNetworkFee`
`timing`	object
`expires_at`	string
`detected_at`	string
`confirmed_at`	string
`paid_at`	string
`created_at`	string
`tx_hash`	string
`explorer_tx_url`	string
`fx_rate_id`	integer
`effective_rate`	string
`cancelled_at`	string
`paid_after_cancel`	boolean
`cancellable`	boolean

CryptoNetwork

Field	Type	Values
`key`	string	`tron`, `ethereum`, `bsc`
`name`	string
`token`	string
`token_note`	string
`chain_id`	integer
`fee_currency`	string	`TRX`, `ETH`, `BNB`
`service_fee`	string
`required_confirmations`	integer
`estimated_time_min_seconds`	integer
`estimated_time_max_seconds`	integer
`network_fee`	`CryptoNetworkFee`

CryptoNetworkFee

Field	Type	Values
`currency`	string
`estimated_native_amount`	string
`estimated_usd_amount`	string
`is_estimate`	boolean
`available`	boolean
`determined_by_wallet`	boolean
`quoted_at`	string
`expires_at`	string

Invoice

Field	Type	Values
`id`	integer
`invoice_number`	string
`type`	string	`topup`, `order_charge`, `renewal_charge`, `refund`, `admin_adjustment`
`direction`	string	`credit`, `debit`
`date`	string
`description`	string
`amount_usd`	string
`rial_amount`	integer
`type_label`	string
`status`	string	`paid`
`status_label`	string
`reference_type`	string
`reference_id`	integer

WalletBalance

Field	Type	Values
`balance_usd`	string
`balance_rial`	integer
`vm_policy`	object
`fx`	object

WalletLedgerEntry

Field	Type	Values
`id`	integer
`type`	string	`topup`, `order_charge`, `renewal_charge`, `refund`, `admin_adjustment`
`amount_usd`	string
`balance_after_usd`	string
`balance_after_rial`	integer
`rial_amount`	integer
`amount_rial`	integer
`type_label`	string
`fx_rate_id`	integer
`reference_type`	string
`reference_id`	integer
`description`	string
`created_at`	string