avnu Developers

curl -X POST "https://starknet.paymaster.avnu.fi" \
  -H "Content-Type: application/json" \
  -H "x-paymaster-api-key: $PAYMASTER_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "paymaster_executeTransaction",
    "params": {
      "transaction": {
        "type": "apply_action",
        "apply_action": {
          "apply_actions_call": { "to": "0x04c9...pool", "selector": "0x02ac...", "calldata": ["0x1", "0x2"] },
          "proof": "base64-encoded-proof",
          "proof_facts": ["0x0123...", "0x0456..."]
        }
      },
      "parameters": {
        "version": "0x1",
        "fee_mode": {
          "mode": "sponsored_private",
          "pool_fee_token": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "tip": "normal"
        }
      }
    }
  }'

import { submitPrivateSwap } from '@avnu/avnu-sdk';

const { transactionHash } = await submitPrivateSwap({
  callAndProof, // { call, proof } from the proving backend
  feeMode: { poolFeeToken: STRK, tip: 'normal' },
  paymasterApiKey: PAYMASTER_API_KEY,
});

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction_hash": "0x06f8...hash",
    "tracking_id": "0x0"
  }
}

POST

curl -X POST "https://starknet.paymaster.avnu.fi" \
  -H "Content-Type: application/json" \
  -H "x-paymaster-api-key: $PAYMASTER_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "paymaster_executeTransaction",
    "params": {
      "transaction": {
        "type": "apply_action",
        "apply_action": {
          "apply_actions_call": { "to": "0x04c9...pool", "selector": "0x02ac...", "calldata": ["0x1", "0x2"] },
          "proof": "base64-encoded-proof",
          "proof_facts": ["0x0123...", "0x0456..."]
        }
      },
      "parameters": {
        "version": "0x1",
        "fee_mode": {
          "mode": "sponsored_private",
          "pool_fee_token": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "tip": "normal"
        }
      }
    }
  }'

import { submitPrivateSwap } from '@avnu/avnu-sdk';

const { transactionHash } = await submitPrivateSwap({
  callAndProof, // { call, proof } from the proving backend
  feeMode: { poolFeeToken: STRK, tip: 'normal' },
  paymasterApiKey: PAYMASTER_API_KEY,
});

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction_hash": "0x06f8...hash",
    "tracking_id": "0x0"
  }
}

Overview

JSON-RPC method paymaster_executeTransaction with the apply_action type. The relayer submits the proven call on-chain and pays the gas; the pool fee (from the build step) reimburses it. No user signature is needed: the transaction settles straight from the proof. Use invoke_and_apply_action to also wrap a signed user call (with the typed_data returned by the build step). The endpoint is the base URL itself (no path): https://starknet.paymaster.avnu.fi (mainnet) or https://sepolia.paymaster.avnu.fi (testnet).

Headers

x-paymaster-api-key

string

required

Portal API key. Required for the sponsored fee modes (sponsored, sponsored_private)

Body (JSON-RPC 2.0)

method

string

required

paymaster_executeTransaction

params.transaction.type

string

required

apply_action, or invoke_and_apply_action when a signed user call is wrapped

params.transaction.apply_action.apply_actions_call

object

required

The proven call, as { to, selector, calldata }

params.transaction.apply_action.proof

string

required

The zero-knowledge proof produced by the proving backend

params.transaction.apply_action.proof_facts

array

required

The proof facts (array of felt hex strings)

params.transaction.invoke

object

Only for invoke_and_apply_action: { user_address, typed_data, signature }

params.parameters

object

required

Same shape as the build step: { version: '0x1', fee_mode, time_bounds? }

Response

transaction_hash

string

required

The hash of the submitted transaction

tracking_id

string

Relayer tracking id

Errors

Code	Name	When
156	`TRANSACTION_EXECUTION_ERROR`	On-chain execution failure
159	`PRIVACY_REQUIRES_SPONSORING`	Private transaction sent without a sponsored fee mode
163	`UNKNOWN_ERROR`	Invalid API key, service unavailable, or blacklisted call
165	`MISSING_FEE_TRANSFER_TO`	The private transaction calldata does not withdraw the pool fee to the paymaster
166	`CALLDATA_PARSING`	The private transaction calldata could not be parsed
167	`POOL_FEE_TOO_LOW`	The withdrawn pool fee is below the required amount
168	`PRIVACY_PROOF_MISSING`	The proof is missing on a private transaction
169	`MAX_L2_GAS_AMOUNT_EXCEEDED`	The transaction exceeds the maximum L2 gas

curl -X POST "https://starknet.paymaster.avnu.fi" \
  -H "Content-Type: application/json" \
  -H "x-paymaster-api-key: $PAYMASTER_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "paymaster_executeTransaction",
    "params": {
      "transaction": {
        "type": "apply_action",
        "apply_action": {
          "apply_actions_call": { "to": "0x04c9...pool", "selector": "0x02ac...", "calldata": ["0x1", "0x2"] },
          "proof": "base64-encoded-proof",
          "proof_facts": ["0x0123...", "0x0456..."]
        }
      },
      "parameters": {
        "version": "0x1",
        "fee_mode": {
          "mode": "sponsored_private",
          "pool_fee_token": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
          "tip": "normal"
        }
      }
    }
  }'

import { submitPrivateSwap } from '@avnu/avnu-sdk';

const { transactionHash } = await submitPrivateSwap({
  callAndProof, // { call, proof } from the proving backend
  feeMode: { poolFeeToken: STRK, tip: 'normal' },
  paymasterApiKey: PAYMASTER_API_KEY,
});

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction_hash": "0x06f8...hash",
    "tracking_id": "0x0"
  }
}

Build Private Transaction Monitor Sponsor Activity

⌘I

API Reference

Execute Private Transaction

Overview

Headers

Body (JSON-RPC 2.0)

Response

Errors

​Overview

​Headers

​Body (JSON-RPC 2.0)

​Response

​Errors

Overview

Headers

Body (JSON-RPC 2.0)

Response

Errors