create_payment_account

POST

/v1/payments/accounts

const url = 'https://app.everruns.com/api/v1/payments/accounts';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"label":"Refund agent · USDC on Base","metadata":"example","owner_id":"identity_01933b5a00007000800000000000001","owner_type":"agent_identity","private_key":"0x<your-32-byte-hex-private-key>","public_address":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e","rail":"x402_base"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.everruns.com/api/v1/payments/accounts \
  --header 'Content-Type: application/json' \
  --data '{ "label": "Refund agent · USDC on Base", "metadata": "example", "owner_id": "identity_01933b5a00007000800000000000001", "owner_type": "agent_identity", "private_key": "0x<your-32-byte-hex-private-key>", "public_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "rail": "x402_base" }'

Create a new payment account.

Request Body^required

application/json

Request body for the create_payment_account operation.

object

label

required

Human-readable label. Safe to render in user-facing messages.

string

Example

Refund agent · USDC on Base

metadata

Free-form metadata attached to this account (caller-defined; opaque to the platform). Example: {"team": "support", "cost_center": "ops"}.

owner_id

required

Prefixed identifier of the owning principal. Must use the prefix that matches owner_type (see above). Example below pairs with owner_type = "agent_identity".

string

Example

identity_01933b5a00007000800000000000001

owner_type

required

Principal class that owns the account. One of: user, agent_identity, organization. The prefix on owner_id must match this: user → user_…, agent_identity → identity_…, organization → org_….

string

Example

agent_identity

private_key

Private key material for the rail. Stored encrypted; never returned in responses. Example shown as an obvious placeholder — supply a real 32-byte hex value at create time.

string | null

Example

0x<your-32-byte-hex-private-key>

public_address

Public address on the rail (chain address, account number, etc.). Optional; can be filled in later.

string | null

Example

0x742d35Cc6634C0532925a3b844Bc454e4438f44e

rail

required

Settlement rail this account operates on. One of: mpp_tempo, x402_base.

string

Example

x402_base

Responses

201

Payment account created

application/json

A payment account — the org-scoped source of funds for paid agent calls. Each account binds an owning principal (user, agent identity, or org) to one settlement rail and tracks its provisioning lifecycle.

object

created_at

required

Timestamp when this account was created (RFC 3339).

string format: date-time

required

Prefixed public identifier. See ID Schema.

string

/^payacct_[0-9a-f]{32}$/

label

required

Human-readable label for this account. Safe to render in user-facing messages.

string

metadata

required

Free-form metadata attached to this account (caller-defined; opaque to the platform).

organization_id

required

Owning organization’s prefixed public identifier.

string

owner_id

required

Prefixed identifier of the owning principal (e.g. user_…, agent_…, org_…).

string

owner_type

required

Principal class that owns this account (user, agent identity, or organization).

string

Allowed values: user agent_identity organization

public_address

Public address on the rail (chain address, account number, etc.). Optional; None until provisioning completes.

string | null

rail

required

Settlement rail this account operates on.

string

Allowed values: mpp_tempo x402_base

status

required

Current lifecycle status of this account.

string

Allowed values: active disabled pending succeeded failed released

updated_at

required

Timestamp when this account was last updated (RFC 3339).

string format: date-time

Example

{
  "created_at": "2026-04-01T10:00:00Z",
  "id": "payacct_01933b5a00007000800000000000001",
  "label": "Production USDC ops wallet",
  "organization_id": "org_01933b5a000070008000000000000001",
  "owner_id": "agent_01933b5a000070008000000000000001",
  "owner_type": "user",
  "public_address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
  "rail": "mpp_tempo",
  "status": "active",
  "updated_at": "2026-05-20T14:00:00Z"
}

400

Invalid input

application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

create_payment_account

Request Body required

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

Example

Request Body^required