Skip to main content
The Timeframe Policy restricts when your agent can execute actions. Essential for scheduled automation, temporary access, and timebounded safety limits.

​
When to Use Timeframe

Subscription payments
Trial periods for new users
Scheduled automation (run only at specific times)
Combining with Sudo for safety

​
Basic Usage

const now = Math.floor(Date.now() / 1000)
const validAfter = now
const validUntil = now + 3600

const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter, // unix-timestamp when policy becomes active
  validUntil  // unix-timestamp when policy expires
});

​
Agent Examples

​
Subscription Agent (Monthly Windows)

Only allow payments once per month for a year 
// Chargeable on day one of the month
const dayOneTimeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter: ..., // unix-timestamp Eg: 1-1-2026 00:00:00 in unix timestamp
  validUntil: ...  // unix-timestamp Eg: 1-1-2026 23:59:59 in unix timestamp
});

// Used only once per month
const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 1n
});

const monthOnePaymentAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [dayOneTimeframePolicy, usagePolicy]
  }
});

// 10 similar actions for 10 months

const monthTwelvePaymentAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [dayOneTimeframePolicy, usagePolicy]
  }
});

// 12 actions which can be executed only once per month on day one for a year.
// Get a session quote and execute it to enable a permission for subscriptions

​
Trial Agent (7-Day Trial)

Limited access for evaluation: 
const SEVEN_DAYS = 7 * 24 * 60 * 60;

const now = Math.floor(Date.now() / 1000)
const validAfter = now
const validUntil = now + SEVEN_DAYS

// Only 7 days trail
const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

// Only 100 trades in trail mode
const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 100n
});

const monthOnePaymentAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [timeframePolicy, usagePolicy]
  }
});

​
Yield Optimizer (Quarterly Rebalancing)

Restrict to specific rebalancing windows: 
// Chargeable in every quarter
const quarterlyTimeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter: ..., // unix-timestamp Eg: 1-1-2026 in unix timestamp
  validUntil: ...  // unix-timestamp Eg: 31-3-2026 in unix timestamp
});

// Used only once per quarter
const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 1n
});

const quarterOneRebalanceAction = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453, 10],
    contractAddress: REBALANCER,
    functionSignature: '0x...',
    policies: [quarterlyTimeframePolicy, usagePolicy]
  }
});

// 2 similar actions for 2 quarters

const quarterFourRebalanceAction = mcNexus.buildSessionAction({
  type: "custom",
  data: {
    chainIds: [8453, 10],
    contractAddress: REBALANCER,
    functionSignature: '0x...',
    policies: [quarterlyTimeframePolicy, usagePolicy]
  }
});

// 4 actions which can be executed only once per quarter for a year.
// Get a session quote and execute it to enable a permissions for rebalancer

​
Delayed Start

Start permissions in the future: 
const ONE_WEEK = 7 * 24 * 60 * 60;

const now = Math.floor(Date.now() / 1000)
const validAfter = now + ONE_WEEK;
const validUntil = validAfter + ONE_WEEK;

const delayedTimeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

// Transfer allowed after a week of delay
const delayedAction = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [delayedTimeframePolicy]
  }
});
Use cases:
  • Scheduled launches
  • Vesting schedules
  • Delayed automation

​
Combining with Other Policies

Timeframe works best combined with other restrictions:

​
Time + No other restrictive policies

const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

const actions = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [timeframePolicy]
  }
});

​
Time + Usage Limit

const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

const usagePolicy = mcNexus.buildActionPolicy({
  type: "usageLimit",
  limit: 5n
});

const actions = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [timeframePolicy, usagePolicy]
  }
});

​
Time + Universal Action

const timeframePolicy = mcNexus.buildActionPolicy({
  type: "timeframe",
  validAfter,
  validUntil
});

const universalPolicy = mcNexus.buildActionPolicy({
  type: "universal",
  rules: [
    {
      condition: "equal",
      calldataOffset: calldataArgument(2),
      comparisonValue: parseUnits("10", 6)
    }
  ],
});

const actions = mcNexus.buildSessionAction({
  type: "transfer",
  data: {
    chainIds: [8453, 10],
    contractAddress: USDC,
    policies: [timeframePolicy, universalPolicy]
  }
});

​
Time Format

All timestamps are Unix timestamps in seconds (not milliseconds): 
// ✅ Correct - seconds
const validUntil = Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60;

// ❌ Wrong - milliseconds
const validUntil = Date.now() + 7 * 24 * 60 * 60 * 1000;

​
Helper Functions

const DAY = 24 * 60 * 60;
const WEEK = 7 * DAY;
const MONTH = 30 * DAY;
const YEAR = 365 * DAY;

const now = () => Math.floor(Date.now() / 1000);
const inDays = (days: number) => now() + days * DAY;
const inWeeks = (weeks: number) => now() + weeks * WEEK;
const inMonths = (months: number) => now() + months * MONTH;