Начало работы
В этом руководстве вы создадите API-пользователя, получите токен доступа и выполните первые запросы к Pert API.
В итоге вы сможете:
- создать API-пользователя;
- создать vault и кошелёк;
- отправить первую транзакцию.
Как работает аутентификация API
Для получения токена доступа используется пара ключей Ed25519:
| Компонент | Описание |
|---|---|
| Секретный API-ключ (приватный ключ) |
Хранится только у вас и используется для подписи авторизационного запроса, чтобы подтвердить, что он отправлен именно вами |
| Публичный ключ | Находится у Pert и нужен для проверки, что запрос действительно подписан вашим приватным ключом |
Приватный ключ остаётся в вашем окружении; Pert получает публичный ключ и проверяет подпись запроса. Защита ключа и полученных Bearer-токенов остаётся на вашей стороне.
Шаг 1: Генерация пары ключей
В запросах к защищённым методам Pert API передавайте JWT-токен доступа:
| Заголовок | Значение |
|---|---|
| Authorization | Bearer JWT_TOKEN |
Для получения токена отправьте запрос, подписанный вашим приватным ключом.
Создайте пару ключей Ed25519 с помощью OpenSSL:
# генерируем приватный ключ
openssl genpkey -algorithm ED25519 -out "pert_secret.pem"
# генерируем публичный ключ
openssl pkey -in "pert_secret.pem" -pubout -out "pert_public.pem"
Команды создадут два файла:
- pert_secret.pem — приватный ключ Ed25519 для подписания запросов;
- pert_public.pem — публичный ключ, который нужно загрузить при создании API-пользователя.
Храните приватный ключ в защищённом хранилище с ограниченным доступом.
Шаг 2: Создание API-пользователя
Чтобы создать API-пользователя для интеграции, выполните следующие шаги:
- В консоли Pert откройте раздел Пользователи → По API
- Нажмите Создать пользователя
- Укажите название, необязательное описание и роль пользователя. Для следующих шагов нужны права на создание vault, кошельков и транзакций; в стандартной конфигурации они есть у роли
SIGNER. - Загрузите файл публичного ключа, созданный на шаге 1
- Нажмите Сохранить
После сохранения, а при включённом согласовании изменений — после одобрения, новый API-пользователь появится в списке. Вы получите API Key (ID API-пользователя) — уникальный идентификатор, который используется вместе с вашим секретным ключом.
Шаг 3: Получение авторизационного токена
Чтобы получить JWT-токен, подпишите данные в формате JSON и вызовите
метод POST /api/v2/auth/access-token.
Подписываемые данные:
| Поле | Тип | Описание |
|---|---|---|
client_type |
string | user для API-пользователя |
client_id |
string | UUID API-пользователя (выдан на шаге 2) |
timestamp |
int64 | Unix-время в секундах. Не старше 5 минут и не более чем на 1 минуту в будущем |
nonce |
string | Новая случайная строка для каждого запроса. Рекомендуется не менее 16 случайных байт, закодированных в Base64 или hex |
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
data |
string | Исходные байты JSON, закодированные в Base64 |
signature |
string | Подпись Ed25519 исходных байтов JSON до кодирования, переданная в Base64 |
Подписываются исходные байты JSON
Подписывается JSON до base64-кодирования. Не подписывайте base64-строку и не меняйте представление JSON после подписания — иначе сервер не сможет проверить подпись.
Используйте серверное время
Если часы вашей системы расходятся с серверными, запросы могут отклоняться с ошибкой
request timestamp too old / too far in future. Получите серверное время через
GET /api/v2/auth/time и используйте его при формировании timestamp.
Пример
import base64
import json
import secrets
import time
import requests
from cryptography.hazmat.primitives.serialization import load_pem_private_key
BASE_URL = "https://auth.pert.paranoid.security"
API_USER_ID = "<API_USER_UUID>"
SECRET_PEM = "pert_secret.pem"
with open(SECRET_PEM, "rb") as f:
private_key = load_pem_private_key(f.read(), password=None)
payload = {
"client_type": "user",
"client_id": API_USER_ID,
"timestamp": int(time.time()),
"nonce": secrets.token_urlsafe(16),
}
data_bytes = json.dumps(payload, separators=(",", ":")).encode()
signature = private_key.sign(data_bytes)
resp = requests.post(
f"{BASE_URL}/api/v2/auth/access-token",
json={
"data": base64.b64encode(data_bytes).decode(),
"signature": base64.b64encode(signature).decode(),
},
timeout=10,
)
resp.raise_for_status()
access_token = resp.json()["access_token"]
package main
import (
"bytes"
"crypto/ed25519"
"crypto/rand"
"crypto/x509"
"encoding/base64"
"encoding/json"
"encoding/pem"
"fmt"
"log"
"net/http"
"os"
"time"
)
func check(err error) { if err != nil { log.Fatal(err) } }
func main() {
pemBytes, err := os.ReadFile("pert_secret.pem"); check(err)
block, _ := pem.Decode(pemBytes)
if block == nil { log.Fatal("invalid private-key PEM") }
keyAny, err := x509.ParsePKCS8PrivateKey(block.Bytes); check(err)
priv, ok := keyAny.(ed25519.PrivateKey)
if !ok { log.Fatal("expected Ed25519 key") }
nonce := make([]byte, 16)
_, err = rand.Read(nonce); check(err)
data, err := json.Marshal(map[string]any{
"client_type": "user", "client_id": "<API_USER_UUID>",
"timestamp": time.Now().Unix(),
"nonce": base64.RawURLEncoding.EncodeToString(nonce),
}); check(err)
body, err := json.Marshal(map[string]string{
"data": base64.StdEncoding.EncodeToString(data),
"signature": base64.StdEncoding.EncodeToString(ed25519.Sign(priv, data)),
}); check(err)
client := &http.Client{Timeout: 10 * time.Second}
resp, err := client.Post("https://auth.pert.paranoid.security/api/v2/auth/access-token",
"application/json", bytes.NewReader(body)); check(err)
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK { log.Fatalf("HTTP %d", resp.StatusCode) }
var token struct {
AccessToken string `json:"access_token"`
ExpiresAt string `json:"expires_at"`
}
check(json.NewDecoder(resp.Body).Decode(&token))
// Сохраните token.AccessToken в памяти; не пишите его в логи.
fmt.Println("Token expires at:", token.ExpiresAt)
}
# подписываемые данные (timestamp — секунды)
DATA_JSON=$(printf '{"client_type":"user","client_id":"%s","timestamp":%d,"nonce":"%s"}' \
"$API_USER_ID" "$(date +%s)" "$(openssl rand -base64 16 | tr -d '=\n')")
# Ed25519 в OpenSSL требует файл с известной длиной входа.
SIGN_INPUT=$(mktemp)
trap 'rm -f "$SIGN_INPUT"' EXIT
printf '%s' "$DATA_JSON" > "$SIGN_INPUT"
DATA_B64=$(base64 < "$SIGN_INPUT" | tr -d '\n')
SIG_B64=$(openssl pkeyutl -sign -inkey pert_secret.pem -rawin -in "$SIGN_INPUT" \
| base64 | tr -d '\n')
curl -X POST https://auth.pert.paranoid.security/api/v2/auth/access-token \
-H "Content-Type: application/json" \
-d "{\"data\":\"$DATA_B64\",\"signature\":\"$SIG_B64\"}"
Ответ:
{
"access_token": "eyJhbGciOi...",
"expires_at": "1777300943056"
}
| Поле | Описание |
|---|---|
access_token |
Bearer-токен, передавайте в заголовке Authorization: Bearer <token> |
expires_at |
Время истечения токена в миллисекундах Unix (строкой) |
Кешируйте токен и обновляйте заранее
Не запрашивайте новый токен на каждый вызов API. Сохраните access_token
и обновите его за ~30 секунд до expires_at, повторив процедуру подписи.
Шаг 4: Создание vault-аккаунта
Все остальные запросы помимо Authorization требуют заголовок X-Workspace-Id —
UUID вашего рабочего пространства. Его можно узнать в консоли (URL …/workspaces/<UUID>/…)
или через GET /api/v1/workspace.
Создайте vault — логический контейнер для адресов в разных валютах:
curl -X POST https://wallet.pert.paranoid.security/api/v1/vault \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"name": "My first vault"}'
Ответ содержит id созданного vault — он понадобится дальше.
Добавьте wallet нужной валюты — для каждой валюты в vault создаётся
отдельный wallet с депозитным адресом. Список доступных валют — GET /api/v1/currencies:
curl -X POST https://wallet.pert.paranoid.security/api/v1/wallet \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"vault_id": "'"$VAULT_ID"'", "currency_id": "'"$CURRENCY_ID"'"}'
Ответ 200 содержит массив assets. Для нужного актива сохраните его id
в SOURCE_WALLET_ID (несмотря на имя параметра, нужен ID актива), а адрес
пополнения возьмите из primary_address.address. Пополните выбранный актив
и базовую монету для комиссии перед переводом.
Шаг 5: Отправка первой транзакции
Перед отправкой можно оценить комиссию через POST /api/v1/transactions/fee —
это не обязательно, но рекомендуется.
Пример ниже отправляет 0.01 ETH: amount — строка целого числа wei
(10^16). Для другого актива используйте его decimals и сумму
в минимальных единицах. Сохраните UUID запроса до отправки и используйте
тот же при повторе.
Создание транзакции:
REQUEST_ID=$(uuidgen) # сохранить и переиспользовать при retry
curl -X POST https://wallet.pert.paranoid.security/api/v1/transaction \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "X-Idempotency-Key: $REQUEST_ID" \
-H "Content-Type: application/json" \
-d '{
"source_wallet_id": "'"$SOURCE_WALLET_ID"'",
"target_address": "'"$TARGET_ADDRESS"'",
"amount": "10000000000000000"
}'
| Заголовок | Описание |
|---|---|
X-Idempotency-Key |
UUID запроса. Повторный запрос с тем же ключом не создаст вторую транзакцию (вернёт 409) |
Ответ 201 Created содержит созданную транзакцию с её id и начальным статусом.
До отправки в сеть транзакция проходит проверки, необходимые согласования
и MPC-подписание. Статус отправки — broadcast, успешного завершения — finished;
возможны declined, failed, expired и другие исходы.
Описание статусов и этапов обработки приведено в справочнике Pert API.
Что дальше
- Авторизация — детали JWT-токенов, обновление, introspect.
- Вебхуки — подпишитесь на события, чтобы получать обновления по транзакциям и депозитам; пропуски восстанавливайте через журнал изменений.
- Pert API — полный справочник методов.
- Коды ошибок — что означают коды ответа и как их обрабатывать.