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

# Create Plans & Agents

> Learn how AI Builders can create Payment Plans and AI Agents

Once you have a Payments instance, you can start creating Payment Plans and AI Agents.

## Creating a Payment Plan

Payment Plans give AI Builders the ability to control how and when users can use an AI agent or service. They are entirely controlled and managed by the AI Builder that creates them with no interference from Nevermined.

Nevermined Payment Plans enable the setup of time-based or request-based gating of a Builder's AI.

* **Request-Based or Credits-Based**: Provides user access with request-gating. Builders can set the target price per request by configuring how many credits each API call consumes. This allows you to control costs based on computational complexity - for example, a simple query might cost 1 credit while a complex analysis could cost 5 credits. When adding services to a Payment Plan, you define the number of credits required per request. Each time a request is made, Nevermined will redeem the specified number of credits. If the user does not have enough credits, they will be prompted to purchase more and denied access until they do.
* **Time-Based**: Provides user access with time-gating. Builders can set the time period that a user is allowed access to the AI (e.g., 1 year, 1 month, 1 week, 1 day, 1 hour, etc.). When a user makes a request, the corresponding access credit is redeemed, granting access for the designated period. Once the time period has elapsed, the user will no longer have access and will need to redeem another credit for continued access.

## Creating a Credit-Based Payment Plan

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const USDC_ERC20_TESTING = '0x036CbD53842c5426634e7929541eC2318f3dCF7e' // This is the USDC ERC20 address in the test network (sandbox)

    const planMetadata = {
      name: 'My Credits Plan',
      tags: ['test']
    }

    // The price is 20 USDC (20_000_000) in the sandbox network
    const priceConfig = getERC20PriceConfig(20_000_000n, USDC_ERC20_TESTING, builderAddress)
    // The subscriber receives 100 credits upon purchasing the plan
    const creditsConfig = getFixedCreditsConfig(100n)
    // Register the plan
    const { planId } = await payments.plans.registerCreditsPlan(
      planMetadata, 
      priceConfig, 
      creditsConfig
    )
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # This is the USDC ERC20 address in the test network (sandbox)
    USDC_ERC20_TESTING = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"

    # Plan metadata
    plan_metadata = PlanMetadata(
        name="My Credits Plan",
        tags=["test"]
    )

    # The price is 20 USDC (20_000_000) in the sandbox network
    price_config = get_erc20_price_config(20_000_000, USDC_ERC20_TESTING, builder_address)
    # The subscriber receives 100 credits upon purchasing the plan
    credits_config = get_fixed_credits_config(100)

    # Register the plan
    response = payments_builder.plans.register_credits_plan(
        plan_metadata,
        price_config,
        credits_config
    )
    plan_id = response.get("planId")
    ```
  </Tab>
</Tabs>

## Creating a Time-Based Payment Plan

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    // The price is 5 USDC (5_000_000) in the sandbox network
    const priceConfig = getERC20PriceConfig(5_000_000n, ERC20_ADDRESS, builderAddress)
    // The plan is valid for 1 day
    const oneDayPlanConfig = getExpirableDurationConfig(ONE_DAY_DURATION)
    // Register the plan
    const { planId } = await payments.plans.registerTimePlan(
      planMetadata, 
      priceConfig, 
      oneDayPlanConfig
    )
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # The price is 5 USDC (5_000_000) in the sandbox network
    price_config = get_erc20_price_config(5_000_000, ERC20_ADDRESS, builder_address)
    # The plan is valid for 1 day
    one_day_plan_config = get_expirable_duration_config(ONE_DAY_DURATION)
    # Register the plan
    response = payments_builder.plans.register_time_plan(
        plan_metadata,
        price_config,
        one_day_plan_config
    )
    plan_id = response.get("planId")
    ```
  </Tab>
</Tabs>

## Creating a Trial Plan

A Trial Plan is a special type of Payment Plan that allows users to try out an AI Agent for a limited time (typically for free). A Trial Plan can only be obtained once by each user.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const trialPlanMetadata: PlanMetadata = {
      name: 'Try it for one day before you buy it',
    }
    // The price is free
    const freeConfig = getFreePriceConfig()
    // The plan is valid for 1 day
    const oneDayPlanConfig = getExpirableDurationConfig(ONE_DAY_DURATION)
    // Register the trial plan
    const { planId } = await payments.plans.registerTimeTrialPlan(
      trialPlanMetadata, 
      freeConfig, 
      oneDayPlanConfig
    )
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Plan metadata for the trial plan
    trial_plan_metadata = PlanMetadata(
        name="Try it for one day before you buy it"
    )

    # The price is free
    free_config = get_free_price_config()
    # The plan is valid for 1 day
    one_day_plan_config = get_expirable_duration_config(ONE_DAY_DURATION)
    # Register the trial plan
    response = payments_builder.plans.register_time_trial_plan(
        trial_plan_metadata,
        free_config,
        one_day_plan_config
    )
    plan_id = response.get("planId")
    ```
  </Tab>
</Tabs>

## Creating an AI Agent

<Note>
  Before creating an AI Agent, you need to have a Payment Plan created.
</Note>

### API Endpoint Configuration

When creating an agent, you need to specify:

* **HTTP methods and URL patterns** that the agent exposes and are protected by the Payment Plan
* **Wildcard support** - You can use wildcards (like `:agentId`) to match dynamic URL segments
* **Open endpoints** - Specify any endpoints that should remain free (like documentation or health checks)

URL patterns support wildcards following the [path-to-regexp](https://github.com/pillarjs/path-to-regexp) specification.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const agentMetadata: AgentMetadata = {
      name: 'E2E Payments Agent',
      tags: ['test'],
      dateCreated: new Date(),
      description: 'Description for the E2E Payments Agent'
    }
    const agentApi = {
      endpoints: [
        { 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' },
        { 'GET': 'https://example.com/api/v1/agents/:agentId/tasks/invoke' }
      ],
      openEndpoints: ['https://example.com/api/v1/rest/docs-json']
    }
    const paymentPlans = [creditsPlanId, expirablePlanId]

    const { agentId } = await payments.agents.registerAgent(
      agentMetadata, 
      agentApi, 
      paymentPlans
    )
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from datetime import datetime

    agent_metadata = {
        "name": "E2E Payments Agent",
        "tags": ["test"],
        "dateCreated": datetime.now().isoformat(),
        "description": "Description for the E2E Payments Agent"
    }
    agent_api = {
        "endpoints": [
            {"POST": "https://example.com/api/v1/agents/:agentId/tasks"},
            {"GET": "https://example.com/api/v1/agents/:agentId/tasks/invoke"}
        ],
        "openEndpoints": ["https://example.com/api/v1/rest/docs-json"]
    }
    payment_plans = [credits_plan_id, expirable_plan_id]

    response = payments_builder.agents.register_agent(
        agent_metadata,
        agent_api,
        payment_plans
    )
    agent_id = response.get("agentId")
    ```
  </Tab>
</Tabs>

## Creating a Payment Plan and AI Agent Together

<Note>
  This method allows you to create the plan and attach the agent to it in one step.
</Note>

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const agentMetadata = { 
      name: 'My AI Payments Agent', 
      tags: ['test2'], 
      description: 'Description for my AI Payments Agent' 
    }
    const agentApi = { endpoints: [{ 'POST': 'http://example.com/test/:agentId/tasks' }] }

    const cryptoPriceConfig = getNativeTokenPriceConfig(500n, builderAddress)
    // Non expirable payment plan
    const nonExpirableConfig = getNonExpirableDurationConfig()

    const { agentId, planId } = await paymentsBuilder.agents.registerAgentAndPlan(
      agentMetadata,
      agentApi,
      planMetadata,
      cryptoPriceConfig,
      nonExpirableConfig,
    )
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Agent metadata and API definition
    agent_metadata = {
        "name": "My AI Payments Agent",
        "tags": ["test2"],
        "description": "Description for my AI Payments Agent"
    }
    agent_api = {
        "endpoints": [
            {"POST": "http://example.com/test/:agentId/tasks"}
        ]
    }

    # The price is 500 native tokens
    crypto_price_config = get_native_token_price_config(500, builder_address)
    # Non expirable payment plan
    non_expirable_config = get_non_expirable_duration_config()

    response = payments_builder.agents.register_agent_and_plan(
        agent_metadata,
        agent_api,
        plan_metadata,
        crypto_price_config,
        non_expirable_config
    )
    agent_id = response.get("agentId")
    plan_id = response.get("planId")
    print('Plan created', response.planDID)
    print('Agent attached', response.agentDID)
    ```
  </Tab>
</Tabs>

## Key Concepts

### Endpoint Protection

When creating an AI Agent, you specify:

* **Protected Endpoints**: Require payment/subscription to access
* **Open Endpoints**: Free to access (e.g., documentation, health checks)
* **URL Patterns**: Support wildcards for dynamic routing

### Payment Plan Types

<CardGroup cols={3}>
  <Card title="Credits-Based" icon="coins">
    Users pay for a specific number of credits. Each request consumes credits based on your configuration.
  </Card>

  <Card title="Time-Based" icon="clock">
    Users get unlimited access for a specific time period (hours, days, months).
  </Card>

  <Card title="Trial Plans" icon="gift">
    Free access for limited time or credits to let users test your service.
  </Card>
</CardGroup>

### Best Practices

<AccordionGroup>
  <Accordion title="Plan Naming">
    Use descriptive names that clearly indicate what the plan offers (e.g., "Basic API Access - 1000 requests").
  </Accordion>

  <Accordion title="Pricing Strategy">
    Start with competitive pricing and adjust based on usage patterns and user feedback.
  </Accordion>

  <Accordion title="Endpoint Design">
    Group related functionality under the same payment plan to provide better value to subscribers.
  </Accordion>

  <Accordion title="Trial Plans">
    Always offer trial plans to reduce barriers to entry and increase conversion rates.
  </Accordion>
</AccordionGroup>

## Next Steps

Once you have created your payment plans and agents, you can:

<CardGroup cols={2}>
  <Card title="Test Purchasing" icon="shopping-cart" href="/integration-guide/order-plans">
    Learn how users purchase your payment plans
  </Card>

  <Card title="Handle Requests" icon="server" href="/integration-guide/process-requests">
    Implement request validation in your AI agent
  </Card>
</CardGroup>