Trades

GET

workspaces

{id}

trades

Trades

curl --request GET \
  --url https://api.tetrafi.io/api/v1/workspaces/{id}/trades \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.tetrafi.io/api/v1/workspaces/{id}/trades', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tetrafi.io/api/v1/workspaces/{id}/trades",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tetrafi.io/api/v1/workspaces/{id}/trades"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tetrafi.io/api/v1/workspaces/{id}/trades")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "orderId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "sourceChain": "<string>",
      "destChain": "<string>",
      "route": {
        "input": {
          "asset": {
            "assetId": "<string>",
            "symbol": "<string>",
            "name": "<string>",
            "decimals": 123,
            "chainId": 123,
            "chainRef": "<string>",
            "address": "<string>"
          },
          "rawAmount": "<string>",
          "decimalAmount": "<string>"
        },
        "output": {
          "asset": {
            "assetId": "<string>",
            "symbol": "<string>",
            "name": "<string>",
            "decimals": 123,
            "chainId": 123,
            "chainRef": "<string>",
            "address": "<string>"
          },
          "rawAmount": "<string>",
          "decimalAmount": "<string>"
        }
      },
      "amountUsd": 123,
      "lpName": "<string>",
      "lpSource": "<string>",
      "routingPathLabel": "<string>",
      "status": "<string>",
      "settlementStatus": "<string>",
      "lifecycleStatus": {
        "flowKind": "<string>",
        "primary": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "isTerminal": true,
        "rank": 123,
        "rawStatus": "<string>",
        "execution": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "settlement": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "withdrawal": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "rawDeferredStatus": "<string>"
      },
      "executionPrice": {
        "value": "<string>",
        "baseSymbol": "<string>",
        "quoteSymbol": "<string>"
      },
      "member": {
        "userId": "<string>",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "<string>",
        "role": "<string>",
        "kycStatus": "<string>",
        "joinedAt": "2023-11-07T05:31:56Z"
      },
      "routingPath": {
        "brokerWorkspaceId": "<string>",
        "brokerName": "<string>"
      },
      "orderKind": "<string>",
      "deferredSettlement": {
        "stage": "<string>",
        "autoWithdraw": true,
        "executedAt": "2023-11-07T05:31:56Z",
        "estimatedSettlementAvailableAt": "2023-11-07T05:31:56Z",
        "settlementWindowHours": 123,
        "withdrawalStatus": "<string>",
        "withdrawalTrackingId": "<string>",
        "withdrawalTxHash": "<string>"
      },
      "settlementSpeedMs": 123,
      "slippageBps": 123
    }
  ],
  "total": 123,
  "offset": 123,
  "limit": 123
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

OpenAPI

/specs/trade-history-api.json get /workspaces/{id}/trades

openapi: 3.1.0
info:
  title: TetraFi Trade History API
  version: '1'
  description: >-
    Read-only, workspace-scoped access to every trade that ran through your workspace - filtered
    lists with offset pagination, single-trade detail keyed by order id, and CSV export, across
    all supported chains.
servers:
  - url: https://api.tetrafi.io/api/v1
security:
  - apiKeyAuth: []
  - bearerAuth: []
paths:
  /workspaces/{id}/trades:
    get:
      summary: Trades
      description: >-
        Lists trades executed under a workspace across every supported chain in one call.
        Filter by status, corridor, RFC 3339 time range, LP, routing path, or USD amount
        range; sort by a whitelisted column; page through results with limit and offset.
      operationId: getTrades
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: Workspace Id
            description: Workspace whose trades are returned - results are scoped to it
          description: Workspace whose trades are returned - results are scoped to it
          example: ws_123
        - name: status
          in: query
          required: false
          schema:
            type: string
            title: Status
            description: Filter by settlement status bucket; pass all (or omit) for every status
          description: Filter by settlement status bucket; pass all (or omit) for every status
          example: settled
        - name: corridor
          in: query
          required: false
          schema:
            type: string
            title: Corridor
            description: Directional corridor as source-dest - matches the trade's source and destination chains
          description: Directional corridor as source-dest - matches the trade's source and destination chains
          example: 84532-11155420
        - name: dateFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
            title: Date From
            description: Only trades created at or after this time (RFC 3339)
          description: Only trades created at or after this time (RFC 3339)
          example: '2026-06-20T00:00:00Z'
        - name: dateTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
            title: Date To
            description: Only trades created at or before this time (RFC 3339)
          description: Only trades created at or before this time (RFC 3339)
          example: '2026-07-20T00:00:00Z'
        - name: member
          in: query
          required: false
          schema:
            type: string
            title: Member
            description: Admin/Owner only - case-insensitive match on member name or email; ignored for other callers
          description: Admin/Owner only - case-insensitive match on member name or email; ignored for other callers
          example: ada@example.com
        - name: lpName
          in: query
          required: false
          schema:
            type: string
            title: LP Name
            description: Case-insensitive match on LP display name or solver id
          description: Case-insensitive match on LP display name or solver id
          example: lp-atlas
        - name: routingPath
          in: query
          required: false
          schema:
            type: string
            title: Routing Path
            description: Filter by routing path type - direct or via_broker; pass all (or omit) for every path
          description: Filter by routing path type - direct or via_broker; pass all (or omit) for every path
          example: direct
        - name: amountMin
          in: query
          required: false
          schema:
            type: number
            title: Amount Min
            description: Minimum trade notional in USD (inclusive)
          description: Minimum trade notional in USD (inclusive)
          example: 100
        - name: amountMax
          in: query
          required: false
          schema:
            type: number
            title: Amount Max
            description: Maximum trade notional in USD (inclusive)
          description: Maximum trade notional in USD (inclusive)
          example: 50000
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            title: Limit
            description: Page size, clamped to [1, 100]
            default: 25
            minimum: 1
            maximum: 100
          description: Page size, clamped to [1, 100]
          example: 25
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            title: Offset
            description: Number of records to skip
            default: 0
          description: Number of records to skip
          example: 0
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            title: Sort By
            description: >-
              Sort column: created_at (default), order_id, member, corridor, amount_usd,
              lp_name, routing_path, settlement_status, settlement_speed_ms - unrecognized
              values fall back to created_at
          description: >-
            Sort column: created_at (default), order_id, member, corridor, amount_usd,
            lp_name, routing_path, settlement_status, settlement_speed_ms - unrecognized
            values fall back to created_at
          example: created_at
        - name: sortDir
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            title: Sort Dir
            description: Sort direction; defaults to desc
            default: desc
          description: Sort direction; defaults to desc
          example: desc
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeListResponse'
        '401':
          description: 'Error Response: Authentication Required'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TradeListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/TradeListItem'
          type: array
          title: Items
          description: Trades in this page
        total:
          type: integer
          title: Total
          description: Total number of trades matching the filters
        offset:
          type: integer
          title: Offset
          description: Offset this page starts at
        limit:
          type: integer
          title: Limit
          description: Effective page size
      type: object
      required:
        - items
        - total
        - offset
        - limit
      title: TradeListResponse
      description: Paginated trade list response.
    TradeListItem:
      properties:
        orderId:
          type: string
          title: Orderid
          description: Order id - the trade's key for detail, timeline, and evidence lookups
        createdAt:
          type: string
          format: date-time
          title: Createdat
          description: When the order was created (RFC 3339)
        member:
          anyOf:
            - $ref: '#/components/schemas/MemberAttribution'
            - type: 'null'
          title: Member
          description: Member who initiated the trade - present for admin/owner callers, omitted otherwise
        sourceChain:
          type: string
          title: Sourcechain
        destChain:
          type: string
          title: Destchain
        route:
          $ref: '#/components/schemas/TradeRouteDisplay'
        amountUsd:
          type: number
          title: Amountusd
          description: Trade notional in USD
        lpName:
          type: string
          title: Lpname
          description: Display name of the LP or provider that filled the trade
        lpSource:
          type: string
          title: Lpsource
          description: How the LP reached this workspace, e.g. Direct, via <broker>, TetraFi Router
        routingPathLabel:
          type: string
          title: Routingpathlabel
          description: Human-readable routing label, e.g. Direct, ViaBroker(...), CCTP Bridge
        routingPath:
          anyOf:
            - $ref: '#/components/schemas/RoutingPath'
            - type: 'null'
          title: Routingpath
        orderKind:
          anyOf:
            - type: string
            - type: 'null'
          title: Orderkind
          description: >-
            Canonical route-aware order kind (cctp-v0 / composite-v0 / fx-v0 / ...) - omitted
            for non-route orders
        status:
          type: string
          title: Status
          description: Canonical user-facing order lifecycle status
        settlementStatus:
          type: string
          title: Settlementstatus
          description: Coarse settlement bucket - the value the status filter matches against
        lifecycleStatus:
          $ref: '#/components/schemas/TradeLifecycleStatus'
        deferredSettlement:
          anyOf:
            - $ref: '#/components/schemas/DeferredSettlementInfo'
            - type: 'null'
          title: Deferredsettlement
        settlementSpeedMs:
          anyOf:
            - type: integer
            - type: 'null'
          title: Settlementspeedms
          description: Milliseconds from order creation to settlement
        executionPrice:
          $ref: '#/components/schemas/ExecutionPriceDisplay'
        slippageBps:
          anyOf:
            - type: integer
            - type: 'null'
          title: Slippagebps
          description: Realized slippage in basis points
      type: object
      required:
        - orderId
        - createdAt
        - sourceChain
        - destChain
        - route
        - amountUsd
        - lpName
        - lpSource
        - routingPathLabel
        - status
        - settlementStatus
        - lifecycleStatus
        - executionPrice
      title: TradeListItem
      description: A single trade in the paginated list view.
    MemberAttribution:
      properties:
        userId:
          type: string
          title: Userid
        firstName:
          type: string
          title: Firstname
        lastName:
          type: string
          title: Lastname
        email:
          type: string
          title: Email
        role:
          type: string
          title: Role
          description: Workspace role of the member
        kycStatus:
          type: string
          title: Kycstatus
        joinedAt:
          type: string
          format: date-time
          title: Joinedat
      type: object
      required:
        - userId
        - firstName
        - lastName
        - email
        - role
        - kycStatus
        - joinedAt
      title: MemberAttribution
      description: Member identity attached to a trade - present for admin/owner callers only.
    TradeRouteDisplay:
      properties:
        input:
          $ref: '#/components/schemas/AssetAmountDisplay'
        output:
          $ref: '#/components/schemas/AssetAmountDisplay'
      type: object
      required:
        - input
        - output
      title: TradeRouteDisplay
      description: Canonical input/output route for display.
    AssetAmountDisplay:
      properties:
        asset:
          $ref: '#/components/schemas/AssetDisplay'
        rawAmount:
          anyOf:
            - type: string
            - type: 'null'
          title: Rawamount
          description: Base-unit amount as a string
        decimalAmount:
          anyOf:
            - type: string
            - type: 'null'
          title: Decimalamount
          description: Human-readable decimal amount
      type: object
      required:
        - asset
      title: AssetAmountDisplay
      description: Raw and normalized amount for one asset side.
    AssetDisplay:
      properties:
        assetId:
          type: string
          title: Assetid
          description: Network-qualified asset identifier
        symbol:
          type: string
          title: Symbol
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        decimals:
          anyOf:
            - type: integer
            - type: 'null'
          title: Decimals
        chainId:
          anyOf:
            - type: integer
            - type: 'null'
          title: Chainid
        chainRef:
          anyOf:
            - type: string
            - type: 'null'
          title: Chainref
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
        resolutionStatus:
          type: string
          enum:
            - resolved
            - unknown
          title: Resolutionstatus
      type: object
      required:
        - assetId
        - symbol
        - resolutionStatus
      title: AssetDisplay
      description: Display identity for one token/asset.
    RoutingPath:
      properties:
        type:
          type: string
          enum:
            - direct
            - via_broker
          title: Type
        brokerWorkspaceId:
          type: string
          title: Brokerworkspaceid
          description: Present when type is via_broker
        brokerName:
          type: string
          title: Brokername
          description: Present when type is via_broker
      type: object
      required:
        - type
      title: RoutingPath
      description: >-
        How the LP reached this workspace: direct bilateral relationship, or via an
        affiliated broker.
    TradeLifecycleStep:
      properties:
        key:
          type: string
          title: Key
        label:
          type: string
          title: Label
        tone:
          type: string
          title: Tone
      type: object
      required:
        - key
        - label
        - tone
      title: TradeLifecycleStep
      description: A compact backend-owned display status step.
    TradeLifecycleStatus:
      properties:
        flowKind:
          type: string
          title: Flowkind
          description: instant, deferred_auto_withdraw, or deferred_manual
        primary:
          $ref: '#/components/schemas/TradeLifecycleStep'
        execution:
          anyOf:
            - $ref: '#/components/schemas/TradeLifecycleStep'
            - type: 'null'
          title: Execution
        settlement:
          anyOf:
            - $ref: '#/components/schemas/TradeLifecycleStep'
            - type: 'null'
          title: Settlement
        withdrawal:
          anyOf:
            - $ref: '#/components/schemas/TradeLifecycleStep'
            - type: 'null'
          title: Withdrawal
        isTerminal:
          type: boolean
          title: Isterminal
        rank:
          type: integer
          title: Rank
        rawStatus:
          type: string
          title: Rawstatus
        rawDeferredStatus:
          anyOf:
            - type: string
            - type: 'null'
          title: Rawdeferredstatus
      type: object
      required:
        - flowKind
        - primary
        - isTerminal
        - rank
        - rawStatus
      title: TradeLifecycleStatus
      description: Backend-owned display status for user-facing execution/settlement state.
    DeferredSettlementInfo:
      properties:
        stage:
          type: string
          title: Stage
        executedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Executedat
        estimatedSettlementAvailableAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Estimatedsettlementavailableat
        settlementWindowHours:
          anyOf:
            - type: integer
            - type: 'null'
          title: Settlementwindowhours
        autoWithdraw:
          type: boolean
          title: Autowithdraw
        withdrawalStatus:
          anyOf:
            - type: string
            - type: 'null'
          title: Withdrawalstatus
        withdrawalTrackingId:
          anyOf:
            - type: string
            - type: 'null'
          title: Withdrawaltrackingid
        withdrawalTxHash:
          anyOf:
            - type: string
            - type: 'null'
          title: Withdrawaltxhash
      type: object
      required:
        - stage
        - autoWithdraw
      title: DeferredSettlementInfo
      description: >-
        Deferred LP settlement/withdrawal tracking, separate from the order's primary
        execution status.
    ExecutionPriceDisplay:
      properties:
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
        baseSymbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Basesymbol
        quoteSymbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Quotesymbol
        source:
          type: string
          enum:
            - stored_quote_price
            - derived_from_amounts
            - unavailable
          title: Source
      type: object
      required:
        - source
      title: ExecutionPriceDisplay
      description: User-facing execution price.
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
      type: object
      required:
        - error
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiError:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code, e.g. AUTH_REQUIRED
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
      type: object
      required:
        - code
      title: ApiError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Workspace API key (tfk_test_/tfk_live_); results are scoped to the key's
        workspace.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Workspace-session JWT; results are scoped to the caller's workspace
        membership.

Authorizations

X-API-Key

string

header

required

Workspace API key (tfk_test_/tfk_live_); results are scoped to the key's workspace.

Path Parameters

string

required

Workspace whose trades are returned - results are scoped to it

Query Parameters

status

string

Filter by settlement status bucket; pass all (or omit) for every status

corridor

string

Directional corridor as source-dest - matches the trade's source and destination chains

dateFrom

string<date-time>

Only trades created at or after this time (RFC 3339)

dateTo

string<date-time>

Only trades created at or before this time (RFC 3339)

member

string

Admin/Owner only - case-insensitive match on member name or email; ignored for other callers

lpName

string

Case-insensitive match on LP display name or solver id

routingPath

string

Filter by routing path type - direct or via_broker; pass all (or omit) for every path

amountMin

number

Minimum trade notional in USD (inclusive)

amountMax

number

Maximum trade notional in USD (inclusive)

limit

integer

default:25

Page size, clamped to [1, 100]

Required range: 1 <= x <= 100

offset

integer

default:0

Number of records to skip

sortBy

string

Sort column: created_at (default), order_id, member, corridor, amount_usd, lp_name, routing_path, settlement_status, settlement_speed_ms - unrecognized values fall back to created_at

sortDir

enum<string>

default:desc

Sort direction; defaults to desc

Available options:

asc,

desc

Response

Successful Response

Paginated trade list response.

items

TradeListItem · object[]

required

Trades in this page

Show child attributes

total

integer

required

Total number of trades matching the filters

offset

integer

required

Offset this page starts at

limit

integer

required

Effective page size

Introduction

Core Concepts

RFQ API

TetraFi propAMM (RFS)

Router API

Price API

Trade History API

OpenAPI

Authorizations

Path Parameters

Query Parameters

Response

​OpenAPI

Authorizations

Path Parameters

Query Parameters

Response

OpenAPI