Transactions

Create Transaction

Create and execute a new transaction through the full pipeline.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "transfer_sol",
    "protocol": "system-program",
    "intent": {
      "destination": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy",
      "lamports": 1000000
    }
  }' \
  http://localhost:3000/api/v1/transactions

Request Body

walletId

string

required

Wallet UUID executing the transaction

type

enum

required

Transaction type: transfer_sol, transfer_spl, swap, stake, unstake, lend_supply, lend_borrow, create_mint, mint_token, query_balance, query_positions, create_escrow, accept_escrow, release_escrow, refund_escrow, dispute_escrow, resolve_dispute, create_milestone_escrow, release_milestone, x402_pay, flash_loan_bundle, cpi_call, custom_instruction_bundle, treasury_allocate, treasury_rebalance, paper_trade

protocol

string

required

Protocol name: system-program, spl-token, jupiter, marinade, solend, metaplex, orca, raydium, escrow

intent

object

Protocol-specific intent payload (see examples below)

agentId

string

Optional agent UUID if executed by an agent

gasless

boolean

default:false

Use gasless transaction submission (if supported by protocol)

idempotencyKey

string

Unique key (8-128 chars) to prevent duplicate transactions

Response

string

required

Transaction UUID

walletId

string

required

Wallet UUID

agentId

string

Agent UUID if executed by agent

type

string

required

Transaction type

protocol

string

required

Protocol name

status

enum

required

Current status: pending, simulating, policy_eval, approval_gate, signing, submitting, confirmed, failed

stage

string

required

Current pipeline stage

signature

string

On-chain transaction signature (once submitted)

intent

object

Original intent payload

policyDecision

object

Policy evaluation result

Show properties

decision

enum

allow, deny, or require_approval

reasons

array

Array of reason strings

riskTier

enum

low, medium, high, or critical

createdAt

string

required

ISO 8601 timestamp

updatedAt

string

required

ISO 8601 timestamp

Transaction Lifecycle

Transactions progress through these stages:

pending → simulating → policy_eval → approval_gate → signing → submitting → confirmed
                                  ↓                                       ↓
                                  └──────────────→ failed ←──────────────┘

Poll the transaction status until it reaches confirmed or failed.

Intent Examples

Transfer SOL
Transfer SPL Token
Swap (Jupiter)
Stake (Marinade)
Query Balance

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "transfer_sol",
  "protocol": "system-program",
  "intent": {
    "destination": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy",
    "lamports": 1000000
  }
}

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "transfer_spl",
  "protocol": "spl-token",
  "intent": {
    "destination": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000"
  }
}

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "swap",
  "protocol": "jupiter",
  "intent": {
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000",
    "slippageBps": 50
  }
}

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "stake",
  "protocol": "marinade",
  "intent": {
    "amount": "1000000000"
  }
}

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "query_balance",
  "protocol": "system-program",
  "intent": {}
}

Read-only queries don’t produce on-chain signatures but still go through policy evaluation.

Get Transaction

Retrieve transaction details and current status.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/transactions/123e4567-e89b-12d3-a456-426614174000

Path Parameters

txId

string

required

Transaction UUID

List Wallet Transactions

List all transactions for a wallet.

cURL

curl -H "x-api-key: dev-api-key" \
     "http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/transactions?limit=20"

Path Parameters

walletId

string

required

Wallet UUID

Query Parameters

limit

number

default:"50"

Maximum transactions to return

offset

number

default:"0"

Number of transactions to skip

status

string

Filter by status: pending, confirmed, failed

Retry Transaction

Retry a failed transaction with fresh blockhash and updated fees.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/transactions/123e4567-e89b-12d3-a456-426614174000/retry

Path Parameters

txId

string

required

Transaction UUID

Retry automatically handles re-simulation, fresh blockhash, and priority fee updates.

Approve Transaction

Approve a transaction paused at approval_gate.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/transactions/123e4567-e89b-12d3-a456-426614174000/approve

Path Parameters

txId

string

required

Transaction UUID

Reject Transaction

Reject a transaction paused at approval_gate.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/transactions/123e4567-e89b-12d3-a456-426614174000/reject

Path Parameters

txId

string

required

Transaction UUID

Get Transaction Proof

Retrieve cryptographic proof of transaction execution.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/transactions/123e4567-e89b-12d3-a456-426614174000/proof

Response

txId

string

required

Transaction UUID

walletId

string

required

Wallet UUID

agentId

string

Agent UUID if executed by agent

intentHash

string

required

SHA-256 hash of intent payload (64 hex chars)

policyHash

string

required

SHA-256 hash of policy evaluation (64 hex chars)

simulationHash

string

required

SHA-256 hash of simulation result (64 hex chars)

signature

string

On-chain transaction signature

proofHash

string

required

SHA-256 hash of complete proof (64 hex chars)

createdAt

string

required

ISO 8601 timestamp

{
  "status": "success",
  "data": {
    "txId": "123e4567-e89b-12d3-a456-426614174000",
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "intentHash": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
    "policyHash": "b2c3d4e5f6a78901bcdef0123456789abcdef0123456789abcdef01234567891",
    "simulationHash": "c3d4e5f6a7b89012cdef01234567890abcdef01234567890abcdef012345678902",
    "signature": "5j7s...",
    "proofHash": "d4e5f6a7b8c90123def012345678901abcdef012345678901abcdef01234567903",
    "createdAt": "2026-03-08T12:00:00.000Z"
  }
}

Get Transaction Replay

Retrieve complete transaction replay data for auditing.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/transactions/123e4567-e89b-12d3-a456-426614174000/replay

Response

Returns full transaction state including:

Original intent
Policy evaluation details
Simulation results
Stage history
Timestamps

Get Pending Approvals

List transactions awaiting approval for a wallet.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/pending-approvals

Path Parameters

walletId

string

required

Wallet UUID

Get Wallet Positions

Query protocol positions (staking, lending, LP) for a wallet.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/positions

Path Parameters

walletId

string

required

Wallet UUID

Get Wallet Escrows

List escrow accounts associated with a wallet.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/escrows

Path Parameters

walletId

string

required

Wallet UUID

Transaction Health Check

Check transaction engine health and RPC pool status.

cURL

curl http://localhost:3006/health

Response

{
  "status": "ok",
  "rpcPool": {
    "healthy": 3,
    "total": 3
  },
  "outbox": {
    "pending": 2,
    "processing": 1
  },
  "timestamp": "2026-03-08T12:00:00.000Z"
}

Overview

Endpoints

Create Transaction

Request Body

Response

Transaction Lifecycle

Intent Examples

Get Transaction

Path Parameters

List Wallet Transactions

Path Parameters

Query Parameters

Retry Transaction

Path Parameters

Approve Transaction

Path Parameters

Reject Transaction

Path Parameters

Get Transaction Proof

Response

Get Transaction Replay

Response

Get Pending Approvals

Path Parameters

Get Wallet Positions

Path Parameters

Get Wallet Escrows

Path Parameters

Transaction Health Check

Response

Overview

Endpoints

​Create Transaction

​Request Body

​Response

​Transaction Lifecycle

​Intent Examples

​Get Transaction

​Path Parameters

​List Wallet Transactions

​Path Parameters

​Query Parameters

​Retry Transaction

​Path Parameters

​Approve Transaction

​Path Parameters

​Reject Transaction

​Path Parameters

​Get Transaction Proof

​Response

​Get Transaction Replay

​Response

​Get Pending Approvals

​Path Parameters

​Get Wallet Positions

​Path Parameters

​Get Wallet Escrows

​Path Parameters

​Transaction Health Check

​Response

Create Transaction

Request Body

Response

Transaction Lifecycle

Intent Examples

Get Transaction

Path Parameters

List Wallet Transactions

Path Parameters

Query Parameters

Retry Transaction

Path Parameters

Approve Transaction

Path Parameters

Reject Transaction

Path Parameters

Get Transaction Proof

Response

Get Transaction Replay

Response

Get Pending Approvals

Path Parameters

Get Wallet Positions

Path Parameters

Get Wallet Escrows

Path Parameters

Transaction Health Check

Response