Activity History

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How to obtain the corporation token
Webhooks	Activity changes are also pushed

Overview

The activity feed is the corporation's transaction record: card payments, bank transfers, corridor
payouts, FX swaps, deposits and fee charges, each as one item carrying its amounts, its rate, its
counterparties and the steps it passed through.

It is where every asynchronous outcome in the Corporate API lands. FX swaps, bulk transfers and
corridor transfers have no status endpoint of their own — the feed is how their completion is observed.

Read the Activity Feed

GET /api/v1/activity/feed

Requires a corporation token. No permission is declared — any authenticated employee can read it.

Query parameters:

Parameter	Type	Required	Description
`page_number`	integer	No	1-indexed page number
`page_size`	integer	No	Defaults to 25. Maximum 50
`sort`	string	No	`name` (default) or `usage`
`types`	array	Conditional	Filter by activity type. Mutually exclusive with `subject`
`subject`	string	Conditional	Filter by wallet address, card id or account reference. Mutually exclusive with `types`

Sending both types and subject is rejected with 400 ErrorInvalidField and
Fields are mutually exclusive. Filter on one dimension per request.

subject must parse as either an address or a UUID. Anything else is rejected with
Invalid format for subject — a bank account's composite <accountId>:<detailsId> is not a valid
subject.

Response:

{
  "data": [
    {
      "id": "64120850-73a1-4df5-a074-d463258c9deb",
      "corporation_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
      "type": "Sepa",
      "sub_type": "Payment",
      "status": "Completed",
      "status_reason": "",
      "direction": "Outbound",
      "created_at": "2024-01-01T10:00:00Z",
      "reference": "Invoice 2024-0042",
      "rrn": "",
      "source": { },
      "destination": { },
      "source_amount": { },
      "destination_amount": { },
      "fee_amount": { },
      "rate": { },
      "recipient": { },
      "reward": { },
      "operations": [
        {
          "hash": "0x28da8dec81198cd43329c92ac5b7bcb048a48495bdbc69fc1c921da72fe42939",
          "operation_amount": { },
          "transaction_amount": { },
          "rate": { }
        }
      ],
      "activity_steps": [
        {
          "type": "Initiated",
          "status": "Completed",
          "status_reason": "",
          "created_at": "2024-01-01T10:00:00Z",
          "completed_at": "2024-01-01T10:00:05Z"
        },
        {
          "type": "CryptoOut",
          "status": "Completed",
          "status_reason": "",
          "created_at": "2024-01-01T10:00:05Z",
          "completed_at": "2024-01-01T10:00:30Z"
        },
        {
          "type": "BankOut",
          "status": "Completed",
          "status_reason": "",
          "created_at": "2024-01-01T10:00:30Z",
          "completed_at": "2024-01-01T18:00:00Z"
        }
      ]
    }
  ]
}

Field	Description
`id`	Activity id. Matches the `id` returned by the transfer that created it
`corporation_address`	Owning corporation
`type`	Activity type — see below
`sub_type`	Finer classification, e.g. `Payment`
`status`	`Pending`, `Completed` or `Failed`
`status_reason`	Free-text reason. Populated on failure
`direction`	`Inbound`, `Outbound` or `Internal`
`reference`	The comment attached to the transfer
`rrn`	Retrieval reference number. Card transactions only
`source` / `destination`	The counterparties — wallet, card, bank account, merchant, external card or external wallet
`source_amount`	What was debited from the source
`destination_amount`	What the destination received
`fee_amount`	Fee charged
`rate`	Average rate applied across the activity
`recipient`	The stored recipient, when the payout named one
`reward`	Reward earned, when any — `Referral`, `Cashback` or `Bonus`
`operations[]`	On-chain operations, each with its hash, amounts and rate
`activity_steps[]`	The stages this activity passes through

Activity Types

Type	Covers
`Deposit`	Funds arriving
`Withdrawal`	Funds leaving
`Exchange`	An asset conversion
`Crypto`	An on-chain transfer
`Sepa`	A SEPA transfer
`FasterPayment`	A Faster Payments transfer
`AchPull`	An ACH debit
`AchPush`	An ACH credit
`Swift`	A SWIFT transfer
`Spei`	A SPEI transfer
`CardTransaction`	A payment on a corporate card
`ExternalCardTransaction`	A payment involving an external card
`CardTransfer`	A push-to-card payout
`CardFeesPayment`	A card issuance or delivery fee
`YieldClaim`	A yield claim

The types filter additionally accepts the corridor types Pix, FpsHk, Imps, Instapay,
BiFast, Nip, Ipp and Pse. An unrecognised value is rejected with
Invalid value for types; matching is case-insensitive.

Activity Steps

activity_steps[] is the audit trail. Each step carries its own status, so a Pending activity shows
exactly where it is:

Step Type	Meaning
`Initiated`	The transaction started
`CryptoIn`	Tokens credited to the corporation
`CryptoOut`	Tokens debited from the corporation
`BankIn`	Fiat received from a bank
`BankOut`	Fiat sent to a bank
`CardIn`	Fiat received from a merchant
`CardOut`	Fiat sent to a merchant
`SyntheticWrap`	Tokens wrapped into synthetic tokens
`SyntheticUnwrap`	Synthetic tokens unwrapped
`Trade`	A stablecoin exchange trade
`Review`	Manual or compliance review
`Reversal`	The transaction was reversed
`Completed`	The transaction was finalised

A Review step means the activity is held for compliance. It is not a failure and will not clear on
a retry. A Reversal step means funds are being returned.

Subject Types

source and destination each carry a subject type:

Wallet · Card · Merchant · ExternalCard · ExternalWallet · SepaBankAccount ·
FasterPaymentBankAccount · AchBankAccount · SwiftBankAccount · SpeiBankAccount ·
CardFeesPayment

Code

const response = await fetch(
  `${baseUrl}/api/v1/activity/feed?page_number=1&page_size=50&types=Sepa&types=Crypto`,
  { headers: { 'Authorization': `Bearer ${corporationToken}` } }
);
const { data: activities } = await response.json();

response = requests.get(
    f"{base_url}/api/v1/activity/feed",
    headers={"Authorization": f"Bearer {corporation_token}"},
    params={"page_number": 1, "page_size": 50, "types": ["Sepa", "Crypto"]},
)
activities = response.json()["data"]

req, _ := http.NewRequest("GET", baseURL+"/api/v1/activity/feed?page_number=1&page_size=50&types=Sepa&types=Crypto", nil)
req.Header.Set("Authorization", "Bearer "+corporationToken)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var feed struct {
    Data []ActivityItemResponse `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&feed)

Withdrawal Requests

GET /api/v1/withdrawal/requests

Requires a corporation token. No permission is declared.

Returns the ERC-20 withdrawals recorded for the corporation and awaiting on-chain execution. These are
prepared calls, not completed movements — the payload carries the encoded call data and its validity
window.

Response:

{
  "data": [
    {
      "account_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
      "to_address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874",
      "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976",
      "amount": 100.0,
      "hash": "0x8A7B6C5D4E3F2A1B0C9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F4A3B2C1D0E9F817",
      "call_data": "3F7D9E1C5A2B804D6E93F7C1A0B5D8E29F4A3B7C6D5E0F1A2B3C4D5E6F7A8B9",
      "valid_after": "2024-01-01T10:00:00Z",
      "valid_before": "2024-01-01T11:00:00Z"
    }
  ]
}

Field	Description
`account_address`	Wallet the withdrawal debits
`to_address`	Destination address
`token_address`	Token being withdrawn
`amount`	Amount to withdraw
`hash`	Hash of the call data and nonce that identifies this request
`call_data`	Encoded contract call for executing the withdrawal
`valid_after`	The request cannot execute before this time
`valid_before`	The request expires at this time

valid_after reflects the ExecutionDelayCorporatePolicy time-lock on the corporation wallet: a
requested withdrawal cannot execute immediately. The window between valid_after and valid_before
is when it can be executed — outside it, the request is dead and must be re-requested.

Pending requests are also delivered to
POST {your_webhook_base_url}/v2/webhooks/erc-withdrawals.

Webhooks

Endpoint: POST {your_webhook_base_url}/v2/webhooks/activities

Delivered when an activity is created or changes status. The payload matches an item of the feed.

Deliveries are not retried and the handler has 10 seconds. Poll the feed for anything you must not
miss — a Pending activity that never produces a delivered webhook is still visible there.

See Webhooks.

Limitations

There is no endpoint that returns a single activity by id. Read the feed and filter on id.
There is no free-text search over activities, and no date-range filter — use
Statements for a period.
page_size is capped at 50.
sort accepts name and usage only; neither orders by time.

Error Handling

{
  "error_reason": "ErrorInvalidField",
  "error_description": "Fields are mutually exclusive",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "types" },
    { "key": "issue", "details": "mutually_exclusive" }
  ]
}

Validation Errors (400)

Error Reason	Error Details	Description	Resolution
`ErrorInvalidField`	`issue: mutually_exclusive`	Both `types` and `subject` were sent	Send one filter
`ErrorInvalidField`	`field: subject`	`Invalid format for subject`	The value must be an address or a UUID
`ErrorInvalidField`	`field: types`	`Invalid value for types`	Use a documented activity type
`ErrorInvalidField`	`field: page_size`, `max: 50`	`page size exceeds maximum allowed`	Request at most 50 per page
`ErrorInvalidField`	`field: sort`, `expected: name\|usage`	`Invalid value for sort`	Use `name` or `usage`

Server Errors (500)

Error Reason	Description	Resolution
`ErrorGeneral`	Feed read failure	The transaction service was unavailable. Retry