Developer Guide

This guide walks you through the entire process of building on Rival - from creating your account to earning from your published tools. Each step is self-contained, so you can jump to any section if you’re already partway through.

Go to cortexone.rival.io/auth/signup and create your account with email, Google, or GitHub. Immediately after signup you’ll be prompted to create an organization - your workspace on Rival. Choose your organization name carefully: it appears in all your tool URLs and marketplace listings and is difficult to change later.

For a full walkthrough of the signup process, see the Quickstart.

Step 2: Verify your phone to unlock welcome credits

After your organization is set up, go to Workspace Settings → Organization and verify your phone number. This unlocks $10 in welcome credits, which you can use to run executions and test your tools before spending anything. Phone verification is also required to participate in the referral program, so it’s worth doing early.

Step 3: Explore the marketplace

Before building, spend a few minutes in the marketplace. Browse tools across different types - Functions, MCPs, Storm - and run a few using your welcome credits. This is the fastest way to understand what a finished, published tool looks like: its documentation, input schema, and execution behavior. It’ll give you a clear target to aim for with your own tools.

Step 4: Create your first tool

In Dashboard, go to Tools and create a new tool. You’ll be asked to give it a name and choose its type. Keep the name descriptive - it’s the first thing other users see in the marketplace, and clear names perform significantly better than vague ones.

For a step-by-step walkthrough of the tool creation flow, see Creating a Tool.

Step 5: Choose your tool type

Rival supports three tool types. Pick the one that matches what your tool needs to do.

Use Function if you’re writing a general-purpose handler: an API integration, data transformation, algorithm, or anything that takes input and returns output.

Use MCP if your tool is designed to be called by AI agents or orchestration frameworks. MCP tools speak JSON-RPC 2.0 and are directly consumable by agent systems.

Use Storm if you need to tag or classify content against a taxonomy you define. You provide the topic file; Storm handles the classification engine.

Step 6: Choose your runtime

For Function and MCP tools, you’ll choose a runtime: Python, JavaScript, or Lua.

Python is the most familiar for data and AI work and has the broadest ecosystem of available libraries. JavaScript and Lua both have significantly faster cold start and execution times, making them better suited for latency-sensitive tools. If your tool does straightforward computation or API calls and response time matters, JavaScript or Lua is worth considering.

Storm tools don’t require a runtime - you work with a topic file instead of code.

Step 7: Write your handler code

The handler is the function that Rival calls when your tool is executed. It receives the input payload and must return a structured response.

Write your handler in the code editor inside the tool builder. The editor provides syntax highlighting and basic error detection. Keep your handler focused - it should do one thing well. If you need to call external services or use environment variables, this is where that logic lives.

For language-specific handler documentation, see the Writing Code section.

Step 8: Define your input schema and events

The input schema defines what data your tool expects. It’s the contract between your tool and anyone calling it - including AI agents that need to understand what parameters are valid.

After defining the schema, create at least one event: a concrete example input with real values filled in. Events serve as test cases and also appear in the tool’s marketplace listing so users can understand what a valid call looks like. A tool with clear example events is far easier to adopt than one with a blank usage tab.

Step 9: Add environment variables if needed

If your handler code needs API keys, secrets, or configuration values, don’t hardcode them. Add them as environment variables in Workspace Settings → API, then assign them to your tool. Environment variables are stored securely and injected at runtime - your code can access them without exposing sensitive values in the codebase.

Step 10: Test with real inputs before publishing

Before your tool goes anywhere near public, run it with real inputs. Use the test interface in the tool builder to execute your saved events and inspect the responses. Check that the output structure matches what you documented, that edge cases are handled gracefully, and that the tool returns clear errors when given invalid input.

Step 11: Set up branding and documentation

Before publishing, fill in your tool’s branding and documentation sections. Add a clear, one-sentence description that explains exactly what the tool does. Write documentation that covers the input schema, expected output format, and any edge cases or limitations.

Good documentation is one of the highest-leverage things you can do as a tool creator. Users decide whether to adopt a tool within the first thirty seconds of reading its listing. A well-documented tool with clear examples outperforms a technically superior but poorly documented one every time.

Step 12: Publish - and choose your pricing

When you’re ready to publish, choose your tool’s visibility and pricing. Private keeps the tool within your organization. Public lists it in the marketplace.

If you’re publishing publicly, decide whether the tool is free or paid. For paid tools, you set the price per execution. You’ll earn 85% of every execution. Consider starting with a price that reflects the value your tool delivers - tools that save significant time or computation can price accordingly.

Step 13: Monitor executions and debug

Once your tool is live, the Executions tab in your dashboard shows every run: input, output, credits consumed, and success or failure status. Monitor this regularly when you’ve just published - real-world inputs often surface edge cases you didn’t test for.

When something fails, the execution log gives you the full error trace. Use it to identify whether the issue is in your handler logic, your input schema validation, or an external dependency your tool relies on.

Step 14: Earn from your tools and set up payouts

As other users run your paid tools, earnings accumulate in your organization’s wallet. To withdraw them, set up your payout method in Workspace Settings → Billing. Payouts are processed on a regular schedule - your wallet balance reflects what’s available to withdraw.

Track your earnings over time from the Billing section. If certain tools are getting traction, that’s signal to invest more in documentation, add more events, or build related tools that complement them.

Step 15: Refer other builders to earn more

If you know other developers who would benefit from Rival, share your referral link from Workspace Settings → Refer & Earn. When someone signs up through your link and builds paid tools, you earn 5% of their tool revenue - from Rival’s platform fee, not the creator’s share. It’s capped at $500 per referred user per year and paid monthly on a Net 30 basis.

For full details on the referral program, see Referral Program.

Tool Types

Deep dives into Function, MCP, and Storm - when to use each and how they work. Read more →

Writing Code

Handler structure, runtime details, and language-specific guides. Read more →

Roles & Permissions

How org roles and tool roles interact - essential reading before adding collaborators. Read more →

FAQs

Answers to the most common questions about credits, publishing, and the platform. Read more →