> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Timeframe Policy

> Control when your agent can act

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

## When to Use Timeframe

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

## Basic Usage

```typescript theme={null}
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

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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):

```typescript theme={null}
// ✅ 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

```typescript theme={null}
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;
```