Перейти к содержанию

Начало работы

В этом руководстве вы создадите 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 — полный справочник методов.
  • Коды ошибок — что означают коды ответа и как их обрабатывать.