Five Methods. Why Less Is More in SDK Design

Five Methods. Why Less Is More in SDK Design.

The hardest design decision we made wasn't what to include. It was what to leave out.

The Agntik SDK has five methods.

agent.pay()
agent.balance()
agent.createTask()
agent.register()
agent.history()

That is the entire public API. Five methods. No more.

When we made this decision, we knew it would generate questions. What about webhooks? What about batch payments? What about service health checks, invoice management, channel operations, routing preferences, fee controls, macaroon handling, HTLC monitoring?

All of those things exist in the underlying infrastructure. Andrés has built them. They work. We chose not to expose them.

This article is about why.

The Cognitive Cost of API Surface

Every method in a public API is a question the developer has to answer before they can start building.

What does this do? When should I use it versus that other method? What are the edge cases? What happens if I call it in the wrong order? What does it return? What can go wrong?

These questions do not disappear when the documentation is good. Good documentation reduces the time spent answering them, but it does not eliminate the cost of answering them. Every method is cognitive overhead. The overhead compounds — ten methods is not twice the cognitive cost of five methods, it is significantly more, because the developer also has to understand the relationships between methods, the ordering constraints, the interaction effects.

There is a name for the phenomenon where adding features makes a product worse: complexity tax. Every feature added to an SDK increases the complexity tax for every developer who uses it. The feature that serves 5% of use cases imposes a tax on the 95% who never use it — because they still have to understand it well enough to know they don't need it.

The Agntik SDK is designed to have the lowest possible complexity tax. Five methods. Understand all five in five minutes. Start building immediately.

The 80% Rule

When we mapped out all the things an autonomous agent might need to do with a payment infrastructure, a clear pattern emerged.

Eighty percent of use cases — the overwhelming majority of what agents actually do in production — reduce to a single operation: pay for a service and receive data.

The remaining twenty percent breaks down roughly as: checking balance before a payment (balance), creating work for a human (createTask), monetizing your own service (register), and auditing what happened (history).

Five methods covers one hundred percent of the use cases that matter, with no method that exists solely for edge cases.

This is not a coincidence. It is the result of asking a question that most SDK designers don't ask explicitly: what is the minimum surface area that covers the maximum percentage of real use cases, with no method that exists only for the tail?

The answer was five.

What We Left Out and Why

The things we chose not to expose are worth examining, because the reasoning is not obvious.

Invoice management. The Agntik SDK handles Lightning invoices internally. When you call pay(), the SDK generates or receives invoices as needed, handles expiry, retries on failure, and abstracts the entire invoice lifecycle away from the developer. Exposing invoice management directly would give developers more control — but it would also make every payment require understanding the Lightning invoice model before you can execute a payment. We made the trade-off: less control, vastly less friction.

Channel operations. Lightning channels — opening, closing, rebalancing — are the plumbing of the payment system. Exposing them would allow developers to optimize routing and manage liquidity. It would also require developers to understand channel management before their agent can pay for anything. We manage channels on behalf of agents. The developer never needs to think about it.

Routing preferences. The SDK chooses payment routes automatically, optimizing for speed and cost. Exposing routing preferences would allow fine-grained control over how payments are routed. It would also require developers to understand the Lightning routing graph. We made the trade-off.

Webhook management. Real-time payment notifications via webhooks are useful for certain architectural patterns. We chose not to expose them in the initial SDK because the pay() method is synchronous — it waits for confirmation and returns the result. When the use case genuinely requires webhooks, we will add them. For now, the synchronous model covers the overwhelming majority of agent workflows.

Macaroon handling. Macaroons — the cryptographic tokens that prove L402 payment — are managed internally by the SDK. Exposing them would allow developers to implement custom authentication flows. It would also require developers to understand macaroon semantics before their agent can make a payment. We made the trade-off.

The pattern in every decision is the same: we traded developer control for developer speed. We made the SDK faster to use by making it less configurable.

The TTFT Metric

We have an internal metric called TTFT — Time To First Transaction.

TTFT measures how long it takes a developer who has never seen the Agntik SDK to go from npm install agntik-sdk to their first confirmed Lightning payment. The target is under ten minutes.

Every design decision in the SDK is evaluated against TTFT. Does adding this method make TTFT shorter or longer? Does adding this configuration option make TTFT shorter or longer? Does adding this error type make TTFT shorter or longer?

Almost always, the answer is: adding things makes TTFT longer.

This is counterintuitive because we tend to think of features as additions. Adding a feature gives the developer more capability. How could that make the developer slower?

The answer is cognitive overhead. A developer encountering an SDK for the first time is trying to build a mental model of what it does and how to use it. More surface area means a larger mental model to build. A larger mental model takes longer to build. TTFT goes up.

The five-method SDK is the SDK that minimizes the time to build an accurate mental model. pay() pays. balance() returns the balance. createTask() creates a task. register() registers a service. history() returns history. The mental model is complete in one sentence per method.

A developer who reads that list knows — with reasonable accuracy — what the SDK does before they have read a single line of documentation. That is the goal.

The Distribution Strategy Hidden in the Design

There is a strategic dimension to the five-method decision that goes beyond developer experience.

Agntik's distribution strategy is developer-led. We do not sell to enterprises through sales cycles. We do not have a marketing budget for paid acquisition. We grow by having developers discover the SDK, integrate it in under ten minutes, experience a confirmed Lightning payment, and tell other developers.

The key moment in this chain is the confirmed payment. A developer who gets to a confirmed payment within ten minutes has a visceral experience of the technology working. That experience is what drives word of mouth. It is what makes a developer tweet about it, write a tutorial, recommend it to a colleague, build a demo.

A developer who spends two hours reading documentation before getting to a confirmed payment has a different experience. They might still be impressed, but the activation energy is different. The likelihood that they will evangelize is lower.

The five-method design is not just about developer experience in the abstract. It is about minimizing the time from discovery to the moment of delight — the confirmed payment at 400 milliseconds, 0.021 sats fee, data in hand. Every method we remove from the API is a barrier we remove from the path to that moment.

The Constraint as Creative Force

There is a principle in design, repeated across disciplines, that constraints produce better work than unlimited freedom.

A poet given a blank page and no rules can write anything. A poet given the constraint of the sonnet form — fourteen lines, specific meter, specific rhyme scheme — is forced to find a solution within a tight space, and the solutions that fit are often better than what unlimited freedom would have produced.

The five-method constraint forced us to make decisions that unlimited freedom would have allowed us to defer. We could not add a sixth method and say "we'll figure out the interface later." Every capability had to fit within five methods or be abstracted away entirely. The constraint made us design the abstractions rather than expose the complexity.

The result is an SDK where pay() does something genuinely complex — queries the Registry, constructs a route, handles L402, manages the invoice, retries on failure, records the transaction, updates the score — and presents it as a single function call with three parameters.

That complexity didn't go away. It went into the SDK, where Andrés handles it, so the developer never has to.

What the Fifth Method Means

The five methods are not created equal. Four of them — pay, balance, register, history — are the mechanics of a payment system. They are necessary, well-understood, and largely expected by any developer who has used a payments SDK before.

The fifth method — createTask() — is different.

createTask() is the method that has no equivalent in any other payments SDK. It is the method that opens the labor market to autonomous agents. It is the method that allows an AI to hire a human, specify the work, set the reward, and pay upon completion — all without any human involvement in the transaction structure.

We could have built a comprehensive task management system with subtasks, workflows, approval chains, dispute resolution, and escalation paths. We chose not to. We built createTask() with three parameters: description, rewardSats, and deadline.

The simplicity is intentional. The first version of a feature that has never existed before should be the simplest version that demonstrates the core capability. createTask() demonstrates that an AI agent can autonomously commission human labor and pay for it with Lightning. That is the capability. Everything else is an enhancement.

The constraint applies here too. One method. Three parameters. The rest can come later, once we understand how agents and humans actually use it in practice.

The Invitation

The five-method SDK is an invitation, not a limitation.

It says: here is the minimum you need to participate in the agent economy. Pay for services. Check your balance. Hire a human. Register your own service. Review your history.

Everything else — the routing, the channels, the invoices, the macaroons, the retries, the fee management — is handled. You do not need to understand it to build on it.

That is what infrastructure should do. It should make the complex invisible, reduce the cost of participation to the absolute minimum, and let builders build.

Five methods. That is the invitation.

Start building.

This is the final article in the Agntik launch series.

Next: The agent that paid for its own infrastructure — a case study from the April 28 demo →