Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.machines.cash/llms.txt

Use this file to discover all available pages before exploring further.

Base URLs:
  • Production: https://api.machines.cash/partner/v1
  • Sandbox: https://dev-api.machines.cash/partner/v1
Get API access: email help@machines.cash or DM @erturkarda on Telegram. All requests are JSON. Use X-Partner-Key for steps 1-2. Use Authorization: Bearer <SESSION_TOKEN> for the rest.

​
1. Create a session token

Call POST /sessions. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Partner-Key: <PARTNER_API_KEY>' \
  --data '
{
  "userId": "eeetest",
  "scopes": [
    "kyc.read",
    "kyc.write"
  ],
  "walletAddress": "0x462B1eD1B62F4c282c0EA342BCefcF8f9919226E",
  "ttlSeconds": 9001
}
'

{
  "ok": true,
  "data": {
    "sessionToken": "<SESSION_TOKEN>",
    "sessionId": "<SESSION_ID>",
    "userId": "eeetest",
    "expiresAt": "2026-01-16T16:47:52.000Z",
    "scopes": [
      "kyc.read",
      "kyc.write"
    ]
  },
  "summary": "session created",
  "errors": []
}
Use this session token for steps 3-9. Call POST /users/resolve. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/users/resolve \
  --header 'Content-Type: application/json' \
  --header 'X-Partner-Key: <PARTNER_API_KEY>' \
  --data '
{
  "userId": "eeetest",
  "walletAddress": "0x462B1eD1B62F4c282c0EA342BCefcF8f9919226E",
  "walletLabel": "Main Wallet"
}
'

{
  "ok": true,
  "data": {
    "userId": "eeetest",
    "walletAddress": "0x462b1ed1b62f4c282c0ea342bcefcf8f9919226e",
    "kycStatus": "not_submitted",
    "createdAt": "2026-01-16T14:17:51.298Z"
  },
  "summary": "user linked; kyc not started",
  "errors": []
}

​
3. Get KYC field requirements and values

Call GET /kyc/values to build your KYC form. The full occupation list is also available at /kyc-values. 
curl --request GET \
  --url https://api.machines.cash/partner/v1/kyc/values \
  --header 'Authorization: Bearer <SESSION_TOKEN>'

{
  "ok": true,
  "data": {
    "fields": [
      {
        "name": "firstName",
        "required": true,
        "type": "string",
        "maxLength": 50,
        "description": "Given name."
      },
      {
        "name": "lastName",
        "required": true,
        "type": "string",
        "maxLength": 50,
        "description": "Family name."
      },
      {
        "name": "birthDate",
        "required": true,
        "type": "date",
        "description": "YYYY-MM-DD (e.g., 1990-01-01)."
      },
      {
        "name": "nationalId",
        "required": true,
        "type": "string",
        "regex": "^[0-9A-Za-z-]+$",
        "description": "Government ID number. Letters, numbers, and dashes only."
      },
      {
        "name": "countryOfIssue",
        "required": true,
        "type": "string",
        "minLength": 2,
        "maxLength": 2,
        "description": "ISO-3166-1 alpha-2 (e.g., US)."
      },
      {
        "name": "email",
        "required": true,
        "type": "string",
        "description": "Valid email address."
      },
      {
        "name": "address",
        "required": true,
        "type": "object",
        "description": "Object with line1, line2, city, region, postalCode, countryCode."
      },
      {
        "name": "phoneCountryCode",
        "required": false,
        "type": "string",
        "maxLength": 3,
        "description": "Country calling code digits only (e.g., 1)."
      },
      {
        "name": "phoneNumber",
        "required": false,
        "type": "string",
        "maxLength": 15,
        "description": "Phone number digits only; include area code."
      },
      {
        "name": "occupation",
        "required": true,
        "type": "string",
        "description": "SOC occupation code (e.g., 49-3023). Use /kyc/values for the list."
      },
      {
        "name": "annualSalary",
        "required": true,
        "type": "string",
        "enum": [
          "<40k",
          "50k–99k",
          "100k–149k",
          "150k+"
        ],
        "description": "Choose a salary range."
      },
      {
        "name": "accountPurpose",
        "required": true,
        "type": "string",
        "enum": [
          "everyday spend",
          "subscriptions",
          "business expenses",
          "testing",
          "other"
        ],
        "description": "How the account will be used."
      },
      {
        "name": "expectedMonthlyVolume",
        "required": true,
        "type": "string",
        "enum": [
          "under $1k",
          "$1k–$5k",
          "$5k–$20k",
          "$20k+"
        ],
        "description": "Choose a monthly volume range."
      }
    ],
    "occupations": [
      { "code": "11-1021", "label": "General and Operations Managers" },
      { "code": "11-2011", "label": "Advertising and Promotions Managers" },
      { "code": "11-3031", "label": "Financial Managers" },
      { "code": "11-9021", "label": "Construction Managers" },
      { "code": "11-9041", "label": "Architectural and Engineering Managers" },
      { "code": "11-9071", "label": "Gaming Managers" },
      { "code": "11-9141", "label": "Property, Real Estate, and Community Association Managers" },
      { "code": "13-1041", "label": "Compliance Officers" },
      { "code": "13-2011", "label": "Accountants and Auditors" },
      { "code": "13-2051", "label": "Financial Analysts" },
      { "code": "13-2052", "label": "Personal Financial Advisors" },
      { "code": "13-2082", "label": "Tax Preparers" },
      { "code": "15-1121", "label": "Computer Systems Analysts" },
      { "code": "15-1131", "label": "Computer Programmers" },
      { "code": "15-1132", "label": "Software Developers, Applications" },
      { "code": "15-1133", "label": "Software Developers, Systems Software" },
      { "code": "15-1141", "label": "Database Administrators" },
      { "code": "15-1142", "label": "Information Security Analysts" },
      { "code": "15-1143", "label": "Computer Network Architects" },
      { "code": "15-1151", "label": "Computer User Support Specialists" },
      { "code": "17-2051", "label": "Civil Engineers" },
      { "code": "17-2071", "label": "Electrical Engineers" },
      { "code": "17-2141", "label": "Mechanical Engineers" },
      { "code": "19-3011", "label": "Economists" },
      { "code": "23-1011", "label": "Lawyers" },
      { "code": "23-2011", "label": "Paralegals and Legal Assistants" },
      { "code": "25-2021", "label": "Elementary School Teachers" },
      { "code": "27-1024", "label": "Graphic Designers" },
      { "code": "27-2012", "label": "Producers and Directors" },
      { "code": "29-1141", "label": "Registered Nurses" },
      { "code": "29-1062", "label": "Family and General Practitioners" },
      { "code": "29-1067", "label": "Surgeons" },
      { "code": "31-9097", "label": "Phlebotomists" },
      { "code": "33-3021", "label": "Detectives and Criminal Investigators" },
      { "code": "35-1011", "label": "Chefs and Head Cooks" },
      { "code": "41-9011", "label": "Demonstrators and Product Promoters" },
      { "code": "41-9021", "label": "Real Estate Brokers" },
      { "code": "43-3071", "label": "Tellers" },
      { "code": "47-1011", "label": "Construction Supervisors" },
      { "code": "47-2061", "label": "Construction Laborers" },
      { "code": "49-3023", "label": "Automotive Service Technicians and Mechanics" },
      { "code": "51-4121", "label": "Welders, Cutters, Solderers, and Brazers" },
      { "code": "53-3032", "label": "Heavy and Tractor-Trailer Truck Drivers" },
      { "code": "53-3041", "label": "Taxi Drivers and Chauffeurs" },
      { "code": "SELFEMP", "label": "Self-Employed" },
      { "code": "UNEMPLO", "label": "Unemployed" },
      { "code": "RETIRED", "label": "Retired" },
      { "code": "OTHERXX", "label": "Other" }
    ],
    "annualSalary": ["<40k", "50k–99k", "100k–149k", "150k+"],
    "expectedMonthlyVolume": ["under $1k", "$1k–$5k", "$5k–$20k", "$20k+"],
    "accountPurpose": ["everyday spend", "subscriptions", "business expenses", "testing", "other"]
  },
  "summary": "kyc values",
  "errors": []
}

​
4. Submit KYC

Call POST /kyc/applications. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/kyc/applications \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "smith",
  "birthDate": "1990-01-01",
  "nationalId": "123456789",
  "countryOfIssue": "US",
  "email": "jsmith@example.com",
  "address": {
    "line1": "123 Main St",
    "city": "New York",
    "region": "NY",
    "postalCode": "10001",
    "countryCode": "US",
    "line2": "Unit 4"
  },
  "occupation": "49-3023",
  "annualSalary": "<40k",
  "accountPurpose": "everyday spend",
  "expectedMonthlyVolume": "under $1k",
  "phoneCountryCode": "1",
  "phoneNumber": "4155551234"
}
'

{
  "ok": true,
  "data": {
    "status": "needs_verification",
    "reason": "",
    "completionLink": {
      "url": "https://kyc.machines.cash/verify",
      "params": {
        "userId": "18717ac1-c375-4ff6-972d-79dd702b7d44",
        "signature": "<KYC_SIGNATURE>"
      }
    },
    "externalVerificationLink": {
      "url": "https://kyc.machines.cash/verify",
      "params": {
        "userId": "18717ac1-c375-4ff6-972d-79dd702b7d44",
        "signature": "<KYC_SIGNATURE>"
      }
    },
    "isActive": true,
    "isTermsOfServiceAccepted": false
  },
  "summary": "kyc submitted",
  "errors": []
}

​
5. Complete verification

Open the completionLink (or externalVerificationLink) in a new window so the user can finish verification.

​
6. Poll KYC status

Call GET /kyc/status until the status is approved. Status meanings are listed in KYC status reference. 
curl --request GET \
  --url https://api.machines.cash/partner/v1/kyc/status \
  --header 'Authorization: Bearer <SESSION_TOKEN>'

{
  "ok": true,
  "data": {
    "status": "approved",
    "reason": "",
    "completionLink": null,
    "externalVerificationLink": null,
    "isActive": null,
    "isTermsOfServiceAccepted": false
  },
  "summary": "kyc status",
  "errors": []
}
Call GET /agreements to fetch agreement text, then POST /agreements to accept. 
curl --request GET \
  --url https://api.machines.cash/partner/v1/agreements \
  --header 'Authorization: Bearer <SESSION_TOKEN>'

{
  "ok": true,
  "data": {
    "agreements": [
      {
        "id": "esignConsent",
        "text": "I accept the E-Sign Consent",
        "links": [
          { "label": "E-Sign Consent", "url": "https://machines.cash/e-sign" }
        ]
      },
      {
        "id": "accountOpeningPrivacyNotice",
        "text": "I accept the Account Opening Privacy Notice",
        "links": [
          { "label": "Account Opening Privacy Notice", "url": "https://machines.cash/account-opening-privacy" }
        ]
      },
      {
        "id": "cardTermsAndIssuerPrivacyPolicy",
        "text": "I accept the Machines Card Terms and the Issuer Privacy Policy",
        "links": [
          { "label": "Machines Card Terms", "url": "https://machines.cash/machines-card-terms" },
          { "label": "Issuer Privacy Policy", "url": "https://www.third-national.com/privacypolicy" }
        ]
      },
      {
        "id": "informationCertification",
        "text": "I certify that the information I have provided is accurate and that I will abide by all the rules and requirements related to my Machines Spend Card.",
        "links": []
      },
      {
        "id": "solicitationAcknowledgement",
        "text": "I acknowledge that applying for the Machines Spend Card does not constitute unauthorized solicitation.",
        "links": []
      }
    ],
    "accepted": false,
    "acceptedAt": null
  },
  "summary": "agreements",
  "errors": []
}

curl --request POST \
  --url https://api.machines.cash/partner/v1/agreements \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accepted": true
}
'

{
  "ok": true,
  "data": {
    "agreements": [
      {
        "id": "esignConsent",
        "text": "I accept the E-Sign Consent",
        "links": [
          { "label": "E-Sign Consent", "url": "https://machines.cash/e-sign" }
        ]
      },
      {
        "id": "accountOpeningPrivacyNotice",
        "text": "I accept the Account Opening Privacy Notice",
        "links": [
          { "label": "Account Opening Privacy Notice", "url": "https://machines.cash/account-opening-privacy" }
        ]
      },
      {
        "id": "cardTermsAndIssuerPrivacyPolicy",
        "text": "I accept the Machines Card Terms and the Issuer Privacy Policy",
        "links": [
          { "label": "Machines Card Terms", "url": "https://machines.cash/machines-card-terms" },
          { "label": "Issuer Privacy Policy", "url": "https://www.third-national.com/privacypolicy" }
        ]
      },
      {
        "id": "informationCertification",
        "text": "I certify that the information I have provided is accurate and that I will abide by all the rules and requirements related to my Machines Spend Card.",
        "links": []
      },
      {
        "id": "solicitationAcknowledgement",
        "text": "I acknowledge that applying for the Machines Spend Card does not constitute unauthorized solicitation.",
        "links": []
      }
    ],
    "accepted": true,
    "acceptedAt": "2026-01-16T16:22:48.186Z"
  },
  "summary": "agreements accepted",
  "errors": []
}

​
8. Discover and create a deposit

Use the deposit flow in this order:
  1. GET /deposits/assets
  2. POST /deposits/range
  3. POST /deposits/estimate
  4. POST /deposits
List assets: 
curl --request GET \
  --url 'https://api.machines.cash/partner/v1/deposits/assets?q=hbar&limit=20' \
  --header 'Authorization: Bearer <SESSION_TOKEN>'
Get range: 
curl --request POST \
  --url https://api.machines.cash/partner/v1/deposits/range \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"currency":"hbar","network":"hbar"}'
Get estimate: 
curl --request POST \
  --url https://api.machines.cash/partner/v1/deposits/estimate \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"currency":"hbar","network":"hbar","amount":25,"amountCurrency":"crypto"}'
Create deposit: 
curl --request POST \
  --url https://api.machines.cash/partner/v1/deposits \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"currency":"hbar","network":"hbar","amount":25}'
Example create response fields:
  • deposit.depositAddress: send funds here.
  • deposit.payinExtraId: memo/tag to include when required by source network.

​
9. Check deposit status and balances

Use GET /deposits/ to check status. Balances typically refresh within a few minutes after completion. 
curl --request GET \
  --url https://api.machines.cash/partner/v1/deposits/<DEPOSIT_ID> \
  --header 'Authorization: Bearer <SESSION_TOKEN>'
Fetch balances with GET /balances: 
curl --request GET \
  --url https://api.machines.cash/partner/v1/balances \
  --header 'Authorization: Bearer <SESSION_TOKEN>'

{
  "ok": true,
  "data": {
    "balances": {
      "creditLimit": 3000,
      "pendingCharges": 0,
      "postedCharges": 0,
      "balanceDue": 0,
      "spendingPower": 3000
    }
  },
  "summary": "balances",
  "errors": []
}

​
Optional: Quote a withdrawal route

Withdrawal flow uses:
  1. GET /withdrawals/assets
  2. POST /withdrawals/range
  3. POST /withdrawals/estimate
  4. POST /withdrawals
Withdrawal routes are dynamic (BTC/SOL/EVM and others). Always query assets, range, and estimate before creating a withdrawal. For create requests, source.contractId is optional. Example estimate request: 
curl --request POST \
  --url https://api.machines.cash/partner/v1/withdrawals/estimate \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "destination": {
      "currency": "hbar",
      "network": "hbar",
      "extraId": "optional-tag"
    },
    "amountCents": 2500
  }'
Create responses include relay metadata (payinAddress, payinExtraId, payoutAddress, payoutExtraId) and execution fields used for onchain signing/broadcast. Execute from the same adminAddress you used in create, and send the tx to execution.callTarget (not the collateral proxy). For coordinator_v2, include the additional admin typed-data signature inputs.

​
10. Create a card session token

For card creation, labels, and card secrets, mint a new session token with POST /sessions. Use this token for steps 11-14. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Partner-Key: <PARTNER_API_KEY>' \
  --data '
{
  "userId": "eeetest",
  "scopes": [
    "crypto.read",
    "crypto.write",
    "cards.secrets.read",
    "cards.write",
    "cards.read"
  ],
  "walletAddress": "0x462B1eD1B62F4c282c0EA342BCefcF8f9919226E",
  "ttlSeconds": 9001
}
'

{
  "ok": true,
  "data": {
    "sessionToken": "<SESSION_TOKEN>",
    "sessionId": "<SESSION_ID>",
    "userId": "eeetest",
    "expiresAt": "2026-01-17T16:32:47.000Z",
    "scopes": [
      "crypto.read",
      "crypto.write",
      "cards.secrets.read",
      "cards.write",
      "cards.read"
    ]
  },
  "summary": "session created",
  "errors": []
}

​
11. Encrypt a card label (optional)

If you want to display a card label to your users, encrypt it with POST /encryption/encrypt and pass it as encryptedName when creating the card. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/encryption/encrypt \
  --header 'Authorization: Bearer <CARD_SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": "Marketing Spend"
}
'

{
  "ok": true,
  "data": {
    "value": {
      "v": 1,
      "iv": "Qz4f2m7Hk1P9x0ab",
      "ct": "Hdbb2yT2F4xWZL5m5bJX3eJb4n8wVhjPzqLw2h7i"
    }
  },
  "summary": "encrypted",
  "errors": []
}

​
12. Create a card

Call POST /cards with an optional card label and limit. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/cards \
  --header 'Authorization: Bearer <CARD_SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "encryptedName": {
    "v": 1,
    "iv": "Qz4f2m7Hk1P9x0ab",
    "ct": "Hdbb2yT2F4xWZL5m5bJX3eJb4n8wVhjPzqLw2h7i"
  },
  "limit": {
    "amountCents": 2500,
    "frequency": "perAuthorization"
  }
}
'

{
  "ok": true,
  "data": {
    "cardId": "9f970d1a-fd8e-41ac-a6fd-5993417942e3",
    "status": "active",
    "brand": "VISA",
    "last4": "4242",
    "expirationMonth": 12,
    "expirationYear": 2029
  },
  "summary": "card created",
  "errors": []
}

​
13. Create a card secrets session

Call POST /cards/secrets/session. 
curl --request POST \
  --url https://api.machines.cash/partner/v1/cards/secrets/session \
  --header 'Authorization: Bearer <CARD_SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "ok": true,
  "data": {
    "sessionId": "<CARD_SECRETS_SESSION_ID>",
    "secretKey": "<CARD_SECRETS_SECRET_KEY>"
  },
  "summary": "card secrets session",
  "errors": []
}

​
14. Fetch card secrets

Call POST /cards//secrets with the session id from the previous step. This returns encrypted PAN and CVC only (not the card label). 
curl --request POST \
  --url https://api.machines.cash/partner/v1/cards/9f970d1a-fd8e-41ac-a6fd-5993417942e3/secrets \
  --header 'Authorization: Bearer <CARD_SESSION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sessionId": "<CARD_SECRETS_SESSION_ID>"
}
'

{
  "ok": true,
  "data": {
    "encryptedPan": {
      "iv": "TTPaDqoFqscIQriDfJ/Efg==",
      "data": "Mo3n8fEUM0yZpaopmfQvaIPmSy8YgEZpyGLbU7vqqvM="
    },
    "encryptedCvc": {
      "iv": "QG5uolhSt7b9MseCnH7ljA==",
      "data": "ruOb8ZRovieujsg34n0EhGWb5w=="
    }
  },
  "summary": "card secrets",
  "errors": []
}

​
15. Decrypt PAN and CVC (server-side)

Use the secretKey from Step 13 to decrypt the card number and CVC. This step is typically handled server-side (or by an agent) and never exposed to the browser. 
import { createDecipheriv } from "crypto";

function decrypt({ iv, data }, keyHex) {
  const key = Buffer.from(keyHex, "hex");
  const payload = Buffer.from(data, "base64");
  const tag = payload.subarray(payload.length - 16);
  const ciphertext = payload.subarray(0, payload.length - 16);
  const decipher = createDecipheriv("aes-128-gcm", key, Buffer.from(iv, "base64"));
  decipher.setAuthTag(tag);
  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
}

console.log("PAN:", decrypt(encryptedPan, secretKey));
console.log("CVC:", decrypt(encryptedCvc, secretKey));