API overview

A REST API with JSON bodies. The pages of this reference are generated from its OpenAPI specification, so they always match the service.

Base URLs

Environment	Base URL	Keys
Testnet: Sepolia, BSC testnet	https://api-testnet.portuna.io	ptn_test_…
Mainnet: Ethereum, BSC	coming soon	ptn_live_…

See Test and live keys.

Authentication

Send your API key in every request:

curl "https://api-testnet.portuna.io/v1/balance" -H "Authorization: Bearer $PORTUNA_API_KEY"

Without a key, or with an unknown or revoked one, the answer is 401 unauthorized; for a disabled account it is 403 partner_disabled. GET /healthz and GET /v1/openapi.yaml need no key.

Formats

• Requests: JSON with Content-Type: application/json, up to 64 KiB. Unknown fields are an error, 400 invalid_json, so a typo in a field name never goes unnoticed.
• Amounts: strings with an integer in the token’s smallest units, such as "1000000": wei for the native coin, 10⁻⁶ for USDT on Ethereum. Strings, because amounts outgrow the integers of many JSON parsers.
• Addresses: 0x-hex in any case; answers give them checksummed (EIP-55).
• Chains: chain_id, the chain’s numeric id, such as 11155111 for Sepolia.
• Times: RFC 3339, in UTC.
• Optional fields without a value are left out of answers.

Lists

GET /v1/sweeps, /v1/revocations, /v1/ledger and /v1/webhook/deliveries return pages, newest first:

{ "items": [ … ], "next_cursor": "eyJ0Ijoi…" }

• limit sets the page size: up to 200, 50 by default.
• Pass next_cursor as cursor to get the next page; on the last page it is null. The cursor is opaque.
• Rows added between your requests neither shift the pages nor repeat.
• A bad parameter gets 400 invalid_query, with the parameter in message.
• The SDKs go through the pages for you: AllSweeps and the like in Go, allSweeps and the like in TypeScript.

Errors

{ "error": { "code": "unknown_token", "message": "token must be a listed ticker, its address or \"native\"" } }

Branch on code, which is stable; message is for people. Every code: Errors and retries. Requests that create sweeps and revocations take an external_id to be safe to retry: see Idempotency.

OpenAPI specification

• openapi.yaml: the OpenAPI 3.1 specification with English descriptions, for code generators and API tools.
• GET /v1/openapi.yaml on the API serves the same specification as the running service knows it.

Resources

AccountBalance of the gas wallet, tariff, settings, ledger and usage.

Hot walletsRegister hot wallets and deploy their delegates.

SweepsCreate, get and list sweeps.

RevocationsRemove delegations from deposit addresses.

WebhookWebhook settings, deliveries and test events.

Webhook eventsHeaders, envelope and data of each event.

ObjectsEvery object with all its fields.

ServiceHealth check and the specification.