Skip to main content

​
Principles for Agents

  • Narrow, explicit schemas (JSON Schema) to remove ambiguity.
  • Idempotency where supported (use Idempotency-Key on card creation).
  • Strict, deterministic error codes; cursor pagination; search + get-by-id pairs.

​
Common Flows

​
Create Fixed-Limit Card (single step)

  1. Optional: POST /encryption/encrypt with the card label, then POST /cards with encryptedName. You can also omit encryptedName and set it later.
  2. Include limit.amountCents and frequency if you want a fixed limit.
  3. Call POST /cards/secrets/session, then POST /cards//secrets to fetch encrypted PAN/CVC.
  4. Optional: DELETE /cards/{cardId} to clean up.

​
Lock / Unlock

  1. PATCH /cards/ with .
  2. Resume with .

​
Open Responses compatibility (optional)

Set X-Open-Responses: 1 on any partner endpoint to receive an Open Responses-style response object. If you already have a tool call id, pass X-Open-Responses-Call-Id so the response includes a function_call_output item with a matching call_id. If omitted, a call id is generated. The response always includes:
  • A message item containing the summary.
  • A function_call_output item containing the full partner envelope as a JSON string.
curl -s \
  -H 'X-Open-Responses: 1' \
  -H 'X-Open-Responses-Call-Id: call_123' \
  https://dev-api.machines.cash/partner/v1/cards

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "machinescash.partner",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "no cards",
          "annotations": [],
          "logprobs": []
        }
      ]
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": "{\"ok\":true,\"data\":{\"cards\":[]},\"summary\":\"no cards\",\"errors\":[]}"
    }
  ]
}
Additional required fields are returned (timestamps, tool_choice, truncation, usage, etc). They are omitted here for readability. Streaming SSE is not supported on partner routes yet.

​
Tool Schemas (LLM-ready)

Use verb-first, namespaced tool names and strict schemas: 
{
  "type": "object",
  "additionalProperties": false,
  "required": ["userId", "walletAddress", "scopes"],
  "properties": {
    "userId": { "type": "string", "maxLength": 120 },
    "walletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
    "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
  }
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "encryptedName": { "type": "object", "required": ["v","iv","ct"], "properties": {
      "v": { "type": "integer" },
      "iv": { "type": "string" },
      "ct": { "type": "string" }
    }},
    "limit": { "type": "object", "required": ["amountCents","frequency"], "properties": {
      "amountCents": { "type": "integer", "minimum": 1 },
      "frequency": { "type": "string", "enum": ["perAuthorization","per24HourPeriod","per30DayPeriod"] }
    }}
  }
}
Include helpful summary strings in responses for LLM chaining, and keep payloads compact.