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

string

required

Wallet UUID executing the transaction

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

string

required

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

object

Protocol-specific intent payload (see examples below)

string

Optional agent UUID if executed by an agent

boolean

default:false

Use gasless transaction submission (if supported by protocol)

string

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

Response

string

required

Transaction UUID

string

required

Wallet UUID

string

Agent UUID if executed by agent

string

required

Transaction type

string

required

Protocol name

enum

required

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

string

required

Current pipeline stage

string

On-chain transaction signature (once submitted)

object

Original intent payload

object

Policy evaluation result

Show properties

enum

allow, deny, or require_approval

array

Array of reason strings

enum

low, medium, high, or critical

string

required

ISO 8601 timestamp

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

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

string

required

Wallet UUID

Query Parameters

number

default:"50"

Maximum transactions to return

number

default:"0"

Number of transactions to skip

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

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

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

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

string

required

Transaction UUID

string

required

Wallet UUID

string

Agent UUID if executed by agent

string

required

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

string

required

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

string

required

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

string

On-chain transaction signature

string

required

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

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

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

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

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

​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