Skip to main content

API

API for user management, transaction handling, and approval workflows.

Version: 1.0

Authentication​

The API supports multiple authentication methods:

  • Bearer Token (JWT): Used for user authentication
  • API Key: Server-to-server authentication using x-api-key header
  • Ethereum Signature: User authentication via x-ethereum-address and x-ethereum-signature headers

Base Endpoints​

App​

Get Hello​

GET /

Basic health check endpoint.

Response: 200 OK

Health Check​

GET /health

Application health status endpoint.

Response: 200 OK

Authentication​

SIWE (Sign-In with Ethereum)​

Generate Nonce​

POST /auth/siwe/nonce

Generates a nonce for SIWE authentication.

Request Body: GenerateNonceDto

Response: 200 OK

Verify SIWE​

POST /auth/siwe/verify

Verifies a SIWE signature.

Request Body: VerifySiweDto

Response: 200 OK

Token Management​

Refresh Token​

POST /auth/refresh

Refreshes an authentication token.

Request Body: RefreshTokenDto

Response: 200 OK

Logout​

POST /auth/logout

Logs out the current session.

Request Body: RefreshTokenDto

Response: 204 No Content

Logout All Sessions​

POST /auth/logout-all

Logs out all sessions for the authenticated user.

Response: 204 No Content

User Information​

Validate Token​

GET /auth/validate

Validates the current authentication token.

Response: 200 OK

Get Current User​

GET /auth/me

Retrieves information about the currently authenticated user.

Response: 200 OK

User Management​

Create User​

POST /users

Creates a new user. Supports both server authentication (x-api-key) and user authentication (ethereum signature).

Request Body: CreateUserDto

Responses:

  • 201 Created - User created successfully
  • 400 Bad Request - Invalid request data or authentication headers
  • 401 Unauthorized - Authentication failed
  • 409 Conflict - User with ethereum address already exists

Get User by Ethereum Address​

GET /users/{ethereumAddress}

Retrieves a user by their Ethereum address. Supports both server authentication (x-api-key) and user authentication (ethereum signature).

Parameters:

  • ethereumAddress (path, required) - Ethereum address of the user

Responses:

  • 200 OK - User found successfully
  • 400 Bad Request - Invalid request data or authentication headers
  • 401 Unauthorized - Authentication failed
  • 404 Not Found - User not found

User API Keys​

Create API Key​

POST /user-api-keys

Creates a new API key for the authenticated user with fixed scopes: transactions:create:own, transactions:approve:own, transactions:read:own.

Request Body:

{
  "name": "My Frontend App Key",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Fields:

  • name (required, max 100 chars) - Name for the API key
  • expiresAt (optional) - Expiration date for the API key

Response: 201 Created

List API Keys​

GET /user-api-keys

Retrieves all API keys for the authenticated user.

Response: 200 OK

Register Encryption Keys​

POST /user-api-keys/register

Registers PGP public key for the authenticated user using their JWT token. Verifies the ECDSA signature against the user's Ethereum address to ensure ownership and registers the account on the blockchain.

Request Body:

{
  "signature": "0x1234...",
  "pgpPublicKey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"
}

Response: 201 Created

Get User Profile​

GET /user-api-keys/profile

Retrieves user profile including PGP and API key information.

Response: 200 OK

Revoke API Key​

DELETE /user-api-keys/{apiKeyId}

Revokes (deactivates) a specific API key.

Parameters:

  • apiKeyId (path, required) - ID of the API key to revoke

Response: 200 OK

Settings​

Get Settings​

GET /settings

Retrieves user settings.

Response: 200 OK

Update Settings​

PUT /settings

Updates user settings.

Request Body: UpdateSettingsDto

Response: 200 OK

Get Settings by Ethereum Address​

GET /settings/by-ethereum/{ethereumAddress}

Retrieves settings for a specific Ethereum address.

Parameters:

  • ethereumAddress (path, required)

Response: 200 OK

Privy Quorum Management​

Update Privy Quorum​

PUT /settings/privy-quorum/{type}

Updates privy quorum settings for a specific type.

Parameters:

  • type (path, required) - Type of quorum (execution or agent)

Response: 200 OK

Get Privy Quorum​

GET /settings/privy-quorum/{type}

Retrieves privy quorum settings for a specific type.

Response: 200 OK

Delete Privy Quorum​

DELETE /settings/privy-quorum/{type}

Deletes privy quorum settings for a specific type.

Response: 200 OK

Register Privy Quorum​

POST /settings/register-privy-quorum

Creates a quorum or returns static quorum configuration. Set navaAgent=true for static Nava Agent quorum, or provide displayName and p256PublicKey for custom quorum creation.

Request Body:

{
  "type": "execution",
  "navaAgent": true,
  "displayName": "My Agent Quorum",
  "p256PublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "message": "Enable agent execution for my account"
}

Fields:

  • type (required) - Type of quorum: "execution" or "agent"
  • navaAgent (optional, default: false) - Use Nava Agent static quorum
  • displayName (required when navaAgent is false)
  • p256PublicKey (required when navaAgent is false)
  • message (optional)

Response: 201 Created

Fireblocks Integration​

Generate CSR​

POST /fireblocks/generate-csr/{type}

Creates a new KMS key and generates a Certificate Signing Request.

Parameters:

  • type (path, required) - Integration type (execution or agent)

Request Body:

{
  "commonName": "My Organization",
  "organization": "My Org",
  "country": "US",
  "organizationalUnit": "Engineering",
  "state": "California",
  "locality": "San Francisco",
  "email": "admin@example.com",
  "recreate": false
}

Required Fields:

  • commonName
  • organization
  • country (two-letter country code)

Responses:

  • 201 Created - CSR generated successfully
  • 409 Conflict - User already has an integration

Get Integration Status​

GET /fireblocks/integration/{type}

Retrieves the current integration status and CSR for a specific type.

Parameters:

  • type (path, required)

Response: 200 OK - Integration details

Get All Integrations​

GET /fireblocks/integrations

Retrieves all integration types (execution and agent) for the user.

Response: 200 OK

Get CSR​

GET /fireblocks/csr/{type}

Returns the generated CSR for upload to Fireblocks.

Parameters:

  • type (path, required)

Responses:

  • 200 OK - CSR details
  • 404 Not Found - No integration found

Complete Integration​

POST /fireblocks/complete/{type}

Saves API credentials and activates the integration.

Parameters:

  • type (path, required)

Request Body:

{
  "apiKey": "your-fireblocks-api-key",
  "vaultAccountId": "vault-account-id",
  "environment": "sandbox",
  "region": "US"
}

Fields:

  • apiKey (required) - Fireblocks API key (X-API-Key)
  • vaultAccountId (required)
  • environment (required) - One of: sandbox, testnet, mainnet
  • region (required) - One of: US, EU, EU2

Responses:

  • 200 OK - Integration completed successfully
  • 404 Not Found - No integration found

Validate Integration​

POST /fireblocks/validate/{type}

Tests the API connection with a harmless request.

Parameters:

  • type (path, required)

Response: 200 OK - Validation result

Get Fireblocks Config​

GET /fireblocks/config/{type}/{ethereumAddress}

Returns Fireblocks configuration needed for the specified integration type.

Parameters:

  • type (path, required) - execution or agent
  • ethereumAddress (path, required)

Responses:

  • 200 OK - Fireblocks configuration for the specified type
  • 404 Not Found - User or integration not found

Create Admin Transaction​

POST /fireblocks/admin/transactions

Create a Fireblocks transaction on behalf of a specific user using specified integration type (defaults to execution).

Request Body:

{
  "escrowAddress": "0x742d35Cc6486C8B9BC0cBe34CB8B6ca7EC440E71",
  "to": "0x1234567890123456789012345678901234567890",
  "value": "1000000000000000000",
  "data": "0x",
  "requestHash": "0x123abc...",
  "type": "execution"
}

Fields:

  • escrowAddress (required) - Ethereum address of the escrow account
  • to (required) - Destination address
  • value (required) - Transaction value in Wei (as string)
  • data (optional) - Contract call data for smart contract interactions
  • requestHash (required) - External transaction ID for tracking
  • type (required) - Integration type: execution or agent (default: execution)

Responses:

  • 201 Created - Transaction created successfully
  • 400 Bad Request - Invalid transaction parameters
  • 401 Unauthorized - Invalid admin API key
  • 404 Not Found - User or Fireblocks integration not found

Transactions​

Get User Transactions​

GET /transactions/users/{ethereumAddress}

Retrieves all transactions for a specified user, including detailed approval information from both user signatures and API keys. Users can only access their own transactions. Server API keys can access any user's transactions.

Parameters:

  • ethereumAddress (path, required)

Responses:

  • 200 OK - Transactions retrieved successfully with approval information
  • 401 Unauthorized - Authentication failed
  • 403 Forbidden - Users can only access their own transactions
  • 404 Not Found - User not found

Create Transaction​

POST /transactions

Creates transactions with automatic routing based on payload type and user settings. Accepts both encrypted (CreateEncryptedTransactionDto) and unencrypted (CreateTrustedTransactionDto) payloads.

  • Encrypted payloads: IPFS + blockchain flow for all execution types
  • Unencrypted payloads: Only allowed for DIRECT_USER execution type, requires admin API key

Responses:

  • 201 Created - Transaction created successfully
  • 400 Bad Request - Invalid request data, PGP validation failed, or invalid flow combination
  • 401 Unauthorized - Authentication failed
  • 403 Forbidden - API key required, insufficient permissions, or unencrypted payload not allowed

Approvals​

Create Approval/Rejection​

POST /transactions/{requestHash}/approvals

Creates an approval or rejection for a transaction. Supports two authentication methods:

User Authentication (Ethereum Signature):

  • Users can only approve/reject their own transactions
  • Requires x-ethereum-address and x-ethereum-signature headers
  • Creates a TransactionApproval record

Server Authentication (API Key):

  • Server API keys can approve/reject any transaction
  • Requires x-api-key header
  • Creates an ApiKeyApproval record

Parameters:

  • requestHash (path, required) - Transaction requestHash to approve/reject

Headers:

  • x-api-key (optional) - API key for server authentication
  • x-ethereum-signature (optional) - Ethereum signature for user authentication
  • x-ethereum-address (optional) - Ethereum address for user authentication

Request Body:

{
  "approved": true,
  "confidence": 0.95,
  "analysis": "Transaction validated successfully",
  "requestHash": "0x123abc..."
}

Fields:

  • approved (required) - true to approve, false to reject
  • confidence (optional) - Orion confidence score (0-1), only for Orion API keys
  • analysis (optional) - Orion analysis result, only for Orion API keys
  • requestHash (optional) - Request hash from blockchain contract, only for Orion API keys

Responses:

  • 201 Created - Approval/rejection created successfully
  • 400 Bad Request - Invalid request data or authentication method
  • 401 Unauthorized - Authentication failed
  • 403 Forbidden - User trying to approve someone else's transaction
  • 404 Not Found - Transaction not found

Get Approval Status​

GET /transactions/{requestHash}/approval-status

Returns the approval status for a transaction, indicating which roles have approved:

  • user: Whether any user has approved the transaction
  • agent: Whether any API key with label='agent' has approved
  • arbiter: Whether any API key with label='arbiter' has approved
  • orion: Whether Orion has approved the transaction

Parameters:

  • requestHash (path, required)

Responses:

  • 200 OK - Approval status retrieved successfully
  • 401 Unauthorized - Authentication failed
  • 404 Not Found - Transaction not found

Privy Quorum​

Create Quorum​

POST /privy-quorum

Creates a new Privy quorum.

Request Body:

{
  "displayName": "Arbiter Quorum for 0x1234...abcd",
  "ethereumAddress": "0x742d35Cc6486C8B9BC0cBe34CB8B6ca7EC440E71",
  "privyUserId": "clm7rv4pu00143..."
}

Response: 201 Created

Verification Services​

Get All Verification Services​

GET /verification-services

Returns a list of all verification services.

Response: 200 OK

Get Active Verification Services​

GET /verification-services/active

Returns a list of all active verification services.

Response: 200 OK

Get Verification Service by ID​

GET /verification-services/{id}

Returns a specific verification service by ID.

Parameters:

  • id (path, required) - Numeric ID

Responses:

  • 200 OK - Verification service found
  • 404 Not Found - Verification service not found

Get Verification Service by Inbox​

GET /verification-services/inbox/{inbox}

Returns a verification service by inbox address.

Parameters:

  • inbox (path, required)

Responses:

  • 200 OK - Verification service found
  • 404 Not Found - Verification service not found

Get Verification Service by PGP Public Key​

GET /verification-services/pgp-public-key/{key}

Returns a verification service by PGP public key.

Parameters:

  • key (path, required)

Responses:

  • 200 OK - Verification service found
  • 404 Not Found - Verification service not found

Internal Endpoints​

Update TEE Proof​

PATCH /internal/orion-metadata/{requestHash}/tee-proof

Updates TEE proof for Orion metadata.

Parameters:

  • requestHash (path, required)

Response: 200 OK

Update Settlement​

PATCH /internal/orion-metadata/{requestHash}/settlement

Updates settlement information for Orion metadata.

Parameters:

  • requestHash (path, required)

Response: 200 OK

Data Models​

Transaction Execution Types​

Transactions support three execution types:

  • 0 - DIRECT_USER: User executes directly
  • 1 - USER_EXECUTED: User-executed with approval workflow
  • 2 - AGENT_EXECUTED: Agent-executed with approval workflow

Transaction Status​

  • PENDING - Transaction awaiting approval
  • APPROVED - Transaction approved
  • REJECTED - Transaction rejected
  • EXECUTED - Transaction executed on blockchain
  • FAILED - Transaction execution failed

Approval Types​

  • user - Approval from user signature
  • admin - Approval from admin API key
  • orion - Approval from Orion verification service

API Key Labels​

  • agent - Agent API key
  • arbiter - Arbiter API key
  • user - User API key
  • orion - Orion verification service key

Error Responses​

All endpoints may return the following error responses:

  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Authentication failed or missing credentials
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., duplicate entry)
  • 500 Internal Server Error - Server error

Error responses include a descriptive message to help diagnose the issue.